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PREFACE 


This manual describes how to write user extensions to the 
Multics Emacs editor. The reader should be thoroughly familiar 
with the Emacs editor, proficient in its use, and acquainted with 
its visible organization. The Emacs Text Editor User's Guide, 
Order No. CH27, provides this necessary information. The 
methods for writing terminal control modules (CTLs) to support 


additional terminal types are also described here. 
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introduction to extension writing. Section provides a short 
course in Lisp, the programming language used for writing 
extensions, and the language in which the Emacs editor itself is 
written. Basically, the extension writer only needs to learn 
enough about Lisp to be able to imitate examples. 


-Section 3 shows, by example, how to write extensions. It 
includes the functions and forms most likely to be needed by the 
extension writer. Section 4 describes LDEBUG mode, the Emacs 
mode for debugging the Lisp code used in extensions. Finally, 
Section 5 demonstrates how to write a CTL to support a new 
terminal type. Again, the CTL writer uses existing CTLs to learn 
to write his own. 


The information and specifications in this document are subject to change without notice. This doc- 
ument contains information about Honeywell products or services that may not be available out- 
side the United States. Consult your Honeywell Marketing Representative. 


@Honeywell Information Systems Inc., 1983 File No.: 1L33, 1U33 
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This manual contains sufficient information to effectively 


and debug Multics Emacs extensions. However, 


ded to be a reference document for either Lisp, 


or Multics MacLisp. Reference documentation for 


avail 


able from: 


MIT Information Processing Center 
Publications Office 

60 Vassar Street 

Cambridge, MA 02139 


Significant Changes in CJ52-Q1A 


New Emacs functions include: 


kill-pop 
kill=raing-top 
reverse-regexp-search 
rotate-kill-ring 


New defcom keywords include: 


been 


and the RCP Users' 


&cleanup 
&epilogue 
&inverse 
&numeric-function 
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cs Programmer's Reference Manual (AG91) 


contains all the reference material from 


eight manuals. 


cs Commands and Active Functions (AG92) 


Guide have been consolidated into a new set of 


the former 


contains all the commands and active functions from the 


former eight manuals. 


cs Subroutines and Input/Output Modules (AG93) 


contains all the subroutines and 1/O modules from the 


former eight manuals. 
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The following manuals are obsolete: 
Name 


MPM Peripheral Input/Output 
MPM Subsystem Writers' Guide 
Programming Tools 
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Resource Control Users' Guide 
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SECTION 1 


INTRODUCTION 


An editor extension is a user-provided capability, which is 
added to the editor to extend its power. It is different from a 
macro, which is simply a collection of editor requests gathered 
up and (perhaps) given a name. Extensions are programs; they are 
written in the language of the Multics Emacs environment. An 
extension is a body of code that augments the editor's 
capability, but does not embed or require knowledge of how data 
in the editor is stored or manipulated. In this sense, all of 
the word, sentence, paragraph, and Lisp-list requests, and the 
various "modes" (e.g., PL/I mode) are extensions. 


The person who wishes to add to his Emacs environment any 
powerful or sophisticated capability must learn to write 
extensions. The keyboard macro facility (*X(, ‘*X)) is not 
intended for such usage. This manual explains how to write 
extensions. 


One of the guiding design principles in the Emacs editor was 
that the creation of editor extensions, either by the editor 
implementors or end users, should be in a programming language of 
established elegance and power. Lisp was the language chosen. 
This primer gives you a Starting point for writing Lisp code to 
run as editor extensions in the Emacs environment. If you have 
some knowledge of Lisp already, it will be of value. However, it 
is assumed in this manual that the reader has no familiarity with 
Lisp, but does, perhaps, with PL/I or BASIC. 


For examples of extension coding, the extension writer's 
ultimate reference material will be the Emacs source. The Emacs 
mail system (RMAIL), FORTRAN and PL/I modes, and the code for the 
word, sentence, and paragraph requests (along with most of the 
other code in the Emacs module e_macops_.lisp) are standard 
examples of extension code. Techniques, styles, and subtleties 
difficult to convey in print may be gleaned by careful study of 
this code. 
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SECTION 2 


AN INTRODUCTION TO LISP 


Lisp programs are built of functions, which are similar to 
procedures or subroutines in other languages, although more akin 
to PL/I and ALGOL functions. You write a Lisp program by 
creating a file full of function definitions. A function 
definition specifies the name of a function, and what it does. 
Here is a sample function definition: 


(defun addandmult (a bc) ;This is a comment 
(* (- a bd) 
(+ a bec))) 


This defines a function named addandmult that takes three 
arguments, called a, b, and c. The addandmult function computes 
the result of multiplying the difference of a and b by the sum of 
a, b, and c, and returns that number as a result, or value. The 
semicolon on the first line above begins a comment; comments 
throughout the examples provide some additional information about 
the code. 


Here is another function definition: 


(defun squareprint (arg) 
(print "The square of") 
(print arg) 
(print "is") 
(print (* arg arg)) 
5) 


This function prints the message "The square of", prints the 
value of its argument, prints the word "is", and prints the value 
of the square of its argument. In addition, it returns the value 
ae The function "“Squareprint”™ has side effects: it causes 
output on the terminal. It also returns a value, the number 5. 
Note that all Lisp functions produce a value; only some produce 
Side effects. The first function defined returns the product of 
those numbers as a value; the second returns 5. 
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If you look at squareprint, you see that it consists of 
Several statements, the "print statements" that print things. 
These statements are called forms, and they are, in fact, calls 
to other functions, in this case the builtin print function. In 
the form: 


(print "The square of") 


the string "The square of" is being passed as an argument to the 
print function. Like all functions, print returns a value, which 
is not used in this case. The side effect of printing something 
does occur. In the form: 


(+ a bc) 


you are invoking the "+" function, which is also builtin. The 
values of the parameter variables a, b, and c are passed to it as 
arguments. It returns a value, which is the requested sum, and 
produces no. side effects. : 


There are five forms in the function-definition for 
squareprint: | 


(print "The square of") 
(print arg) 

(print "is") 

(print (* arg arg)) 

5 


, Forms immediately inside a function definition are executed 
sequentially, like statements in other programming languages. 
The value produced by the last form is the one the function 
itself returns. What does it mean to "execute" a 5? Execute is 
not exactly the right term; what really happens is that these 
forms are evaluated. This means that a value is produced from 
them. Evaluating a 5 produces the number 5; evaluating the form: 


{+ a boc) 
calls the "+" function with the appropriate arguments, and 
produces whatever value the "+" function returns. The value 


produced by the "print" function is something that is not. 
interesting, but a value is produced. 
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Numbers, like 5, and strings, like "The square of", are said 
to evaluate to themselves. Things between parentheses, like: 


(#2 Doc) | 
(print "The square of") 


are calls to functions, which are evaluated by calling the 
function indicated, and producing the value it returns. 


Function calls have the syntax: 

(FUNCTIONNAME ARGFORM1 ARGFORM2 ARGFORM3 ... ARGFORMn) 
where FUNCTIONNAME is the name of the function to call and the 
ARGFORMS are themselves forms, which are evaluated to produce the 
arguments to give to the function. Thus, to evaluate (i.e., 
"execute" and find the value returned) a form like: 


(+ (* a 5b) 


i5 
Cc) 

2 evaluate the inner form (* a b) to produce a value 

g evaluate the 15 to produce 15 (remember, numbers and 
strings evaluate to themselves) 

S evaluate the variable c to produce its value 

& pass these three values on to the "+" function, and 


return what it returns. 


The newlines are ignored. 


Thus, forms are either numbers like 5, strings like "is", 
variables like b, or function calls like (* a b). 


Variables are much like variables in other languages. A 
variable has a value, which is called its binding. At this 
Stage, assume that this value must be a string or a number. When 
a function is invoked, the parameter variables (like a, b, andec 
above) of the function acquire the arguments of the function call 
as bindings. Evaluating a variable produces its binding as a 
value. For instance, if someplace in a function you evaluate the 
form: 


(addandmult 2 (+ 3 2) 6) 
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a, b, and c will have the bindings 2, 5, and 6 while the forms in 
the definition of addandmult are being evaluated. This is not 
unlike the subroutine parameter mechanism in other languages. It 
is different insofar as it specifies what value a variable has 
during "Subroutine" execution. In PL/I or FORTRAN, a parameter 
is associated with a variable in the calling program, nota 
value, during subroutine execution. 


There are parameter variables, as used above, temporary 
variables, described below, and global variables. Regardless of 
the kind of variable, they all have bindings (values), and 
evaluation of the variable produces that value. 


To summarize: 
1. Lisp programs are built of functions. 


Ze Function definitions consist of the word "“defun", the 
function's name, a parameter list, anda number of 
forms, which are to be sequentially evaluated at 
function call time, with a pair of parentheses around 


ning. 


3. The value of the last form in a function is the value 
returned by that function. 


4, Forms can be strings, numbers, variables, or calls to 
functions. Forms are evaluated to produce values, 
which are passed between. functions aS arguments and 
results. 


Ds Strings and numbers evaluate to themselves. 


6. Variables evaluate to the datum to which they are 
bound, which, for a parameter, is the corresponding 
argument to the containing function. 


re Function calls contain the name of a function to call 
and forms that are evaluated to produce the arguments 
to the function. Function calls may produce side 
effects. Like any form, when a function call is 
evaluated, it produces a value. | 
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PREDICATES 


Programming languages need conditional execution. In order 
to control conditional execution, you need things upon which to 
base a decision. Two data objects in the Lisp world correspond 
to truth and falsity, for the purposes of parts of the Lisp 
System that deal with conditions. A set of functions called 
predicates return these objects as values. For instance, a 
function called ">", invoked as: 


(> 4 6) 
returns the indicator of falsity, and when invoked as: 
(> 4 1) 


returns the indicator of truth. Predicates work just like other 
builtin and nonbuiltin functions, like print, addandmult, 
squareprint, and +. They take arguments, and produce a result. 
In the case of predicates, however, the result is not a string or 
a number, but an indication of truth or falsity. The result of a 
predicate can be used by the if special form (see below) to 
control the execution of a function. 


The following are some of the most useful Lisp predicates. 
In all of these examples, Al, A2, S1, O01, etc., stand for forms, 
which means they can be 12, (+ 6q), (myfun 33 (- a b)), etc. 
"Al is a number," below, means that Ai is some form which 
evaluates to a number, such as 3, (+ 6 2), or x49, if x49's value 
1S indeed a number. 


Predicate for Numbers 
Al and A2 are numbers: 


Predicate Example Returns TRUTH if ..., otherwise falsity. 


= (= Al A2) Al and A2 are the same number. 
> (> Al A2) Al is a bigger number than A2. 
< (< Al A2) Al is a smaller number than A2. ; 
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Predicates for Strings 
$1 and S2 are strings: 


samepnamep. 

(samepnamep Si S2) 
Sl and S2 are strings of identical content, i.e., the 
"Same string". This is the standard way to see if two 
Strings are the same, as in (Samepnamep test "-hold") 


alphalessp 

(alphalessp Si $2) 
SI collates before SZ alphabetically, e.g., 
(alphalessp “Able” "Baker") returns truth, but 
(alphalessp "Zeke" "Joe”) does not. 


Predicates for Any Objects 


Ol is some object, of perhaps unknown type (objects are 
discussed later): 


eq (eq 01 02) 01 and 02 are the same symbol 
or the same cons. 


fixp (£ixp O1) O01 is a number, as opposed to 
some other kind of object. 


stringp (stringp 01) O1 is a string, as opposed to 
anything else. 


symbolp (symbolp 01) O01 is a symbol, as opposed to 
anything else. 


mull (null O01) O01 is not only a symbol, but 

the important and 

critical symbol named "nil". 

LISP SPECIAL FORMS 
A number of special forms in Lisp do not go by the simple 

rules given above. You have already seen one. The 
function-defining form, which begins with the word "defun", is 
not simply a function call with forms to produce the function's 
arguments. By all rights, a form like: 


(defun square (x) 
(* & x)) 


Should evaluate, in order, to produce arguments for "“defun": 


ae A variable named "square". 
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2. The form, (x), calling a function named "x" with no 
arguments. 


ce The form, (* x x), multiplying the value of a variable 
named "x" by itself, 


This form should then pass these three values on to the defun 
LuUnCL LON: This, however, is not what actually happens. 
Evaluating the defun form causes a function named Square to be 
defined, whose parameter list and "body" are as given. Defun is 
a special form, and when Lisp sees "defun"” as the function name 
in a form, 1t acts in a special way. In this case, Lisp defines 
a function built out of this form itself. The above is nota 
call to defun with arguments. It may seem unusual, but you must 
have at least one such special form in order to have an operative 
Lisp system. 


The if Special Form 


A special form in the Multics Emacs Lisp environment, called 
if, controls conditional evaluation. An example of its use: 


(defun which-is-greater (first second) 
(if (> first second) 
(print "The first one is the greater.”) 
else : 
(if (> second first) 
(print "The second one is greater”) 
else 


The syntax of if is as followss | 


(if <PREDICATE> 
<THEN-FORM-1> 
<THEN-FORM-2> 
<THEN-FORM-m> 

else 
<ELSE-FORM-1> 
<ELSE-FORM-2> 


<ELSE-FORM-n> ) 


Any number, including none, of THEN-FORMS can be supplied. 
Similarly, any number, including none, of the ELSE~FORMs can be 
given. If there are no ELSE-FORMs, then the keyword "else" may 
be omitted, too. 


2=% CJ52-01 


Note that all the forms inthe if are not sequentially 
evaluated; the word else is not even intended to be a form. If 
all of the forms inside the if were evaluated, it would be 
useless, for evaluation would not be conditional. That is why if 
is a special form; there are special rules about how forms inside 
it are to be evaluated. The rule for all nonspecial forms is the 
Same: you evaluate all the subforms sequentially to produce the 
arguments to the function. Each special form has its own rules. 


The if special form evaluates the PREDICATE: if it results 
im truth, the THEN-FORMS are sequentially evaluated, and the 
value of the last one is returned as the value of the if. 
Otherwise, the ELSE-FORMs are evaluated sequentially, and the 
value of the last returned. Tf there are none, the symbol nil 
(see below) is returned. 


There are two global variables in Lisp, called "t" and 
"nil", whose bindings are always the truth and falsity 
indicators, respectively. Thus: 


(print "Not so truth") ) 


when evaluated, always prints "Truth". 


| The actual object used as the indicator of falsity is the 

symbol named nil (see "Symbols" below). All predicates return 
this symbol to indicate falsity. The usual indicator of truth is 
the symbol named t; however, all special forms and functions that 
test predicates consider any object, other than nil, to be an 
indicator of truth. Thus, many functions return the symbol named 
nil to indicate failure and some “good” value (not nil) to 
indicate success. 


The setq Special Form 


Variables acquire values by being parameters, and acquiring 
values at function call time. In addition, variable values can 
be changed by the special form setq: 


(defun adder-of-one (x) 
(print "The value of x is”) 
(print x) 
("And the val 


(setq x (+ xl 
(print x)) 


ue of x olus one is") 
w W in a rou WH bE ee ow j 
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A setq form has the word "Setg", the name of a variable, and an 
inside form. The inside form is evaluated, and that value 
assigned to the variable. It is like an assignment statement in 
other languages. 


The do-forever and stop-doing Special Forms 


The construct for looping in the Emacs Lisp environment is 
also a special form, called do-forever: 


(do-forever 
(print "Yay Multics") 
(print "scitluM yaY")) 


When evaluated, it prints these two sayings forever. The way you 
stop doing in a do-forever is to evaluate the stop~doing special 
form: 


(defun print-n-times (n) 
(do-forever 
(if (= n 0)(stop-doing) ) 
(print "foo") 
(setq n (~ n 1)))) 


This function, given a number as an argument, prints "foo" that 
many times. The "=" builtin function/predicate compares its two 
arguments, which must be numbers, and returns truth or falsity 
‘depending on whether or not they are numerically equal. The 
arguments to = are not n and 0, but rather, the numbers that are 
the bindings of n and 6. The number which is the binding of n is 
different each time around the loop; that is the point of the 
program. It is setq that changes the value of n each time 
around, as do-forever executes the loop. A do-forever form 
generally returns something useless (nil), unless you exit by 
Saying (return 5) or (return nil), or (return a). In the latter 
case, the value of the variable a is returned. 


The let Special Form 


You can acquire temporary variables via the let special 


form: 


(defun sumtimesdif (x y) 
(let ((sum (+ x y)) 
(dif (- x y))) 
(print "Sum times difference is ") 
(print (* sum dif)) 
(print "Sum squared is”) 
(print (* sum sum)))) 
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This function has two temporary variables, sum and dif, which are 
initialized to the values of (+ x y) and (- x y). The general 
Syntax of let is: 


(let ((VARL VAL1) 

(VAR2 VAL2) 

(VARn VALN) ) 
<FORM1> 
<FORM2> 


ee Oo & & & & & 


<FORMm> ) 


The temporary variables VAR1...VARn exist only within the 
let. They get the initial values of VAL1 through VALn, which are 
forms that will be evaluated. All the VALs are evaluated before 
any of their values are assigned to the VARs. Then, with all 
these temporary variables set up and initialized, each FORMi is 
evaluated sequentially, and the value of the last FORMi is 
returned by let. 


Another, less useful way of acquiring temporary variables is 
via the special form prog. Forms inside a prog are evaluated 
sequentially, like forms in a function definition. However, the 
first form in a prog is not really a form at all, but a list of 
temporary variables used in the prog, such as "(a bc)". That is 
why prog iS a special form. The value returned by prog is 
usually useless, unless (return...) is used to return something 
meaningful. 


Inside a prog, you can put labels, to use for go-to's: 


(defun bar2 (x y) 
(prog () snote the empty variable list 
(i1£ (< x y)(go labl)) 
(print "X is not less than Y") 


(return nil) *return "false" indication 
labl 


(print "so be it!") 
(return t))) *return "true" indication 


In the special form go, its operand (not argument) is a label to 
which to go, i.e., continue sequential evaluation of forms in the 
prog. Labels are rarely needed, due to the powerful if and 
do-forever constructs. 
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The or And and Special Forms, And not 


There are special forms for or-ing and and-ing predicate 
results: they are special because they stop evaluating their 
operands (from which arguments are produced) when they "know" 
their answer for certain: 


(if (and (not (= x 0)) 
(> (/7 10 x) 5)) 
(print "Quotient too large.")) 


The not function inverts truth and falsity. The double slash 


indicates division, because slash is the escape character in 
Lisp. 


The and does not attempt to evaluate the second form within 
it 1 the first produces falsity. This prevents an error that 
would result if an attempt were made to divide by zero. 
Sequential execution and stopping at an intermediate result are 
defined and useful features here, as opposed to the logical 
‘operators of, say, PL/I. | 


The progn, progi, and prog2 Special Forms 


Three more special forms are progn, progi, and prog2. To 
force sequential execution of forms and return the value of the 
last, use progn. For instance: : 


(if (and (> x 3) 
(progn (print "Oh dear this is getting serious") 
(> y 5)) ; 
(print "Fatal difficulty"))) - 


In the above, progn returns the value of its last form. Thus, 
the and tests whether x is greater than 3, and y is greater than 
5, before the "print" of "Fatal difficulty" is evaluated. The 
printing of "Oh dear..." occurs as part of the evaluation of the 
progn, but the and sees only the second value in the progn. The 
progn is used to force evaluation of the print form. 
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A progi is just like progn, except that it returns its first 
argument, evaluated, rather than its last. It must have at least 
two arguments. It is useful for saving some value that is 
subsequently going to be destroyed. The following form, when 
evaluated, interchanges the values of x and y: 


(setq x (progl y the value of y is obtained here, 
| and remembered as it is here. 

x is evaluated, and that value 

assigned to y. The value of 


setq form is that value. 


(setq y x))) 
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In the above, however, the value of progi is that value of y as 
it was before it was assigned into y, and now the outer setgq 
assigns that to x. A prog2 is an older form of progi and is 
Similar, except it returns its second argument. 


SYMBOLS 


Another type of data object in Lisp is called the symbol. 
Symbols are named data objects kept in a registry of symbols (the 
obarray), by Lisp. For current purposes, there is only one 
symbol of any name. Symbols are used in Emacs to represent 
buffer names, and various quantities associated with buffers. 
Lisp uses symbols to keep track of functions, and internally to 
keep track of global variables. 


To use a symbol in a program, give the name (the printname) 
of the symbol preceded by an apostrophe ('). For instance, the 
form: 


(setq x 'Brunhilde) 


assigns the symbol named Brunhilde to x. Note that this is 
different from: 


(setq x "Brunhilde") 
which assigns the string Brunhilde to x, and from: 
(setq x Brunhilde) 


which assigns the value of the variable Brunhilde to x. 
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LISP LISTS 


The final Lisp data type of importance in writing extensions 
is the cons (for construct), and the larger data type built out 
of it, the list. A cons is a block that relates to two (usually 
other) objects in the environment, known as its car and its cdr. 
The function cons, given two objects, produces a new cons, whose 
car and cdr, respectively, are the two objects given. For 
instance, if the variable x has a vaiue of the string 
"Brunhilde", as above, then: 


(cons 7 x) 


produces a cons whose car is the number 7 and whose cdr is the 
String "Brunhilde”", returning it as a value. The functions car 
and cdr can be used to obtain the car and cdr of a cons. If you 
set the. variable c to the result of the form (cons 7 x) above, 
then: 


(car c) 


produces the number 7 as a value. 


Usually, you make larger and larger structures out of 
conses, by setting up conses whose car and cdr are more conses, 
and so forth, until you have a large enough structure to 
represent all the values you need. The resulting construction 
serves the same purpose as a PL/I structure: its various parts 
have meaning assigned by the programmer. 


The most common construction of conses is the list. A list 
is defined as a chain of conses, each of which has the next one 
in the chain as its cdr, except the last one, which has the 
symbol "nil" as its cdr. A list built in this way of n conses is 
called alist of n elements, the elements being the n objects 
that are the cars of the conses. The cons at the head of the 
list is identified as being "the list": its car is the first 
element in the list, its cdr is the cons whose car is the second 
element of the list, and so forth. To construct a list of the 
numbers 2, 4, 5, and 7, in that order, and set the variable b to 
it, you would need: 


(seta b (cons 2 (cons 4 (cons 5 (cons 7 nil))))) 


(Note that the variable "nil" is peculiar insofar as its value is 
always the symbol "nil", thus you need not say ‘'nil.) 


2-13 CJ52-01 


A function that simplifies the writing of such forms, for 
constructing lists, builds lists directly and accepts any number 
of arguments. It produces the same result as the type of 
construction shown above. It is called "list": 


(setq b (list 2 4 5 7)) 


To get. the third element of the list, once this form is 
evaluated, you could evaluate the form: 


(car (cdr (cdr b))) 


(i.e., the car of the cons that is the cdr of the cons that is 
the cdr of the cons that is the value of b). Again, there are 
Lisp functions to simplify such constructions. The above form is 
equivalent to: 


(caddr b) 


In general, for up to 4 cars and cdrs deep, total, functions like 
cadr, cdar, caddr, cadar, and so forth, are provided (up through 
caaaar and cddddr). The first four elements of a list are gotten 
by car, cadr, cas and cadddr (it isa good exercise to work 


, 
. kha aan 
ify why this is the case). 


When lists are printed out by Lisp, they are represented as 
a pair of parentheses around the printed representations of all 
of the elements, in sequence, separated by spaces. Thus, if Lisp 
printed out the list that was b's value above, it would appear: 


(2 4 5 7) 


A cons whose cdr is the symbol nil can always be viewed as a list 
of one item, and is so printed out by Lisp, unless it is in the 
process of printing a larger list of which the cons at issue is a 
chain-link. A cons whose cdr is neither nil nor another cons is 
printed with a dot preceding the cdr. Thus: 


(cons 'a 'b) => (a. b) 
(cons 'a nil) => (a) ;a list of one element 
(cons 'a (cons 'b 'c)) => (ab. c) 
(cons 'a (cons 'b nil)) => (a b) :list of two elements 
(cons 'a (cons (cons 'b 'c)(cons 'd nil))) 
=> (a (b . cc) d) ;list of three elements 
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Lists can be put into programs, by quoting them, as symbols 
are quoted: 


(setq bl '({this is (a list)(of lists))) 


Two functions are provided to redefine the car or cdr of an 
existing cons. They can be very dangerous if misused, especially 
if they alter a list as in the form above, which is written into 
a program as a constant. The rplaca function (replace car) and 
the rplacd function (replace cdr) each take two arguments. The 
first is the cons that is to be altered, and the second is the 
new car or new cdr, respectively. The returned value is the cons 
itself. 


Other list Primitives 

A variant of list, list*, is just like list except its last 
argument becomes the cdr of the last cons constructed. That is, 
list*, given n arguments (n > 2), constructs a list of its first 
n-i arguments; the same as list given those n-1 arguments, but 
instead of the last cons having nil as its cdr, the nth argument 
is made its cdr. Thus, 

(list*® 2.35 7) a> (2 3-5) «> 7) 
Note that: 


(list 2 3 5 7) 


and: 


(ii sti-2. 35:5) => 


Another function for manipulating Lisp lists is append. It 
accepts any number of arguments, each of which is a list of zero 
or more elements, and constructs a list containing all the 
elements of all the lists, in order. Thus, 


"(able baker) ‘(2 3)) 
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The append function constructs anew list. A "destructive" 
form of append, called nconc, creates the result it returns by 
"patching" its input arguments to create a longer list, i.e., it 
changes the cdr of the last cons of each input list to be the 
first cons of the next list. The nconc function must be used 
with caution; e.g., it is always an error to give a constant 
(1.@., a quoted piece of list structure) as an argument to nconc. 


Another Lisp function for dealing with Lisp lists is 
reverse. Given a list, it returns a list with the same elements 
as the input list but in reverse order. The nreverse function is 
Similar to reverse but, like nconc, does its work by 
destructively modifying the input list. 


A superlative method for writing code that builds list 
Structure is provided by the Lisp "backquote” facility. The 
backquote facility is described in Appendix A. 


LISP MACROS 


List Structure as Code 


One of the most powerful features of Lisp is the ability of 
Lisp programs to manipulate Lisp programs easily. The internal 
representation of Lisp programs during compilation and debugging 
is that of Lisp lists. You may have noticed that Lisp lists 
Strongly resemble pieces of Lisp programs. For example, the 
form: 


(setq x (+ y 2Z)) 


is simply a printed representation of a list of three elements: 
the symbol setq, the symbol x, and the list (itself of three 
elements) of the symbols +, y, and z. Thus, a form is simply a 
Piece of Lisp structure that is intended to be evaluated. In 
fact, the eval function does precisely that; given a piece of 
list structure, i.e., a form, as an argument, eval evaluates it 
and returns the value of that form. Note how symbols represent 
both functions and variables, depending upon where they appear in 
forms. Symbols have bindings, which represent the binding of the 
variable represented by the symbol, and functional properties via 
which the associated function or code for a special form can be 
found. Thus, if the symbol (and thus variable) f£ is bound to: 
(setq x (+ y 2)) 

and y is bound to 3, and z is bound to 4, then evaluation of the 
symbol (variable) £ would produce: 
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(setq x (+ y Z)) 
a list of three elements. Evaluation of: 
(eval f) 


would pass that list of three elements as an argument to eval, 
causing its evaluation, which would cause x to have a binding of 
7 and return 7 as a result. 


In some sense, the basic action of Lisp is that of 
evaluation. However, user programs, other than Lisp debuggers or 
interpreters, rarely use the eval function. If you think you 
have to use eval (except sometimes in macros; see below), you are 
probably having difficulty with the concept of evaluation. 


Using Lisp Macros 


Lisp macros, allow a user to specify the translation of code 
with a syntax of his choosing into code representing the meaning 
he assigns to that syntax. A macro is defined just like a 
function, except that the word (symbol) "macro" (without 
quotation marks) appears between the function name and the 
parameter list. For instance: | 


(defun t-return macro (x) 
(append (cons 'progn (cdr x)) 
"(t))) 


defines a macro named t-return. When the compiler or interpreter 
sees a form whose car (i.e., where the function name belongs) is 
a symbol that has a macro definition (as above) associated with 
it, it passes the entire form to the macro as an argument, runs 
the macro (i.e., calls it with that argument), and reconsiders 
the result as if it were encountered in place of the original 
form. Thus, if a program contains a form: 


(and (> x 15) 
(t-return (setq flag nil)) 
(return x)) 


. A M4 -~ ~ mom a =o aie ae | ne. 
h me this form is evaluated or compiled, in place of the 


(progn (setq flag nil) t) 
will be evaluated or compiled. This is because t-return has been 
defined as a macro; the function defined by t-return, when called 
with: 


(t-return (setq flag nil)) 
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as an argument, produces: 
(progn (setq flag nil) t) 


as a value. The fact that t-return has been defined as a macro 
causes the compiler to invoke t-return to translate the t-return 
form into its meaning, so that can be compiled or evaluated in 
its place. 


The backquote facility (see Appendix A) is extremely useful 
for defining macros. Using backquote, you could define the macro 
above as: 


(defun t-return macro (x) 
*‘(progn ,@(cdr x) t)) 


See Appendix A for another example of a macro. Additional 
examples of macro definitions are contained in the 
e-macros.incl.lisp include file (after the first two pages if you 
dprint it). Bear in mind when studying them, however, that they 
reference internal Emacs variables and functions or embed certain 
knowledge that they are designed to hide. 


PRINTED REPRESENTATION OF LISP OBJECTS 

Lisp objects exist in the Lisp or Emacs environment. They 
relate to each other, and they denote each other. The calling of 
functions, whether built-in, Emacs-provided, or user-provided, 
creates new objects and changes the relationships among existing 
objects. 


Objects are symbols, conses, and strings in the Lisp 
environment; they are not parentheses and words on paper or ina 
buffer. However, you often need to obtain the printed 
representation of a Lisp object or generate a Lisp object based 
upon its printed representation. This is most commonly the case 
with numbers; in Emacs, the decimal-rep function obtains the 
printed representation of a decimal number as a string. 


The Lisp explode function creates a list of the 
Single-character symbols representing the printed representation 
of the argument that was given. Passing such a list to the Lisp 
maknam primitive produces a symbol whose printname is that 
printed representation; that symbol is as good as a string for 
any purpose in Lisp or Emacs. Instead of maknam, the Emacs 
apply-catenate primitive can be used to produce a string and may 


be more efficient. 
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The conversion of numbers by explode is controlled by two 
global variables, base and *nopoint: base is the output radix, 
which is eight by default, indicating octal; *nopoint is nil, 
indicating that numbers are to be converted with a decimal point 
if base happens to be ten. Thus: 


(let ((base 10.) 
(*nopoint t)) 
(apply-catenate (explode x))) 


obtains the printed representation of the value of x, with 
numbers converted as decimal, without decimal points. 


read-from-string 


The Lisp read-from-string function constructs Lisp objects 
from strings (or symbols with a meaningful printname). Given a 
valid printed representation of a Lisp object, read-from-string 
recurSively constructs (for lists), creates (for mumbers or 
.Strings), or finds on the obarray (for symbols) the appropriate 
objects. Thus, if x is bound to the string "(a bc)", the form: 


(read-from-string x) 


would produce as a value a list of the three symbols a, b, andc. 
In converting numbers with read-from-string, integers followed by 
a decimal point (e.g., 6., 27., and 259., but not 5.0, which is 
floating point) are converted as decimal. Unpointed integers are 
converted as per the value (as radix) of the ibase global 
Variable, which is normally eight. Thus, 


(let ((ibase 10.)) 
(read-from-string x)) 


converts the value of x with all unpointed numbers assumed 
decimal. i 
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SECTION 3 


WRITING EMACS EXTENSIONS 


Writing extensions is basically a matter of building new 
functions out of the standard functions provided in the Emacs 
Lisp environment. These new functions can be hooked up to keys 
in the same fashion as standard Emacs functions, via the set-key 
and set-permanent-key functions. 


Many useful extensions can be made simply by stringing 
together groups of Emacs requests. For instance, to go to the 
beginning of a line, delete all whitespace there, go to the end 
of the line, do the same, and then return to the beginning of the 
line, you could type: 


AAR ESC \ 4B ESC \ 4A 


Alternatively, you could write a function, called shave-line 
here, to do the same: 


(defun shave-line () skeystroke functions take no args. 
(go-to-beginning-of-line) ; function hooked to “A key 
(delete-white-sides) : £unction hooked to ESC \ key 
(go-to-end-of-line) ; function hooked to “E key 
(delete-white-sides) ; ESC \ 
(go-to-beginning-of-line)) ; “A 

Write this function into a file. When in Emacs, type ESC X 

loadfile PATHNAME CR, to load it in as code. Then hook it up, 

perhaps by typing (when typing this, type the caret key for %, 
not the control key): 
ESC X set-key “XA shave-line CR 


Thereafter, hitting *XA (control KX A) causes your new shave-line 
function to be run. 


i a CJ52-01 


If you want a function that goes to the beginning of a line 
and deletes all words that start with "foo" from the beginning of 
the line, for example, you need to use Emacs conditionals and 
variables. 


($include e-macros) 


(defun foodeleter () 
(go-to-beginning-of-line) 
(do-forever 

(if (looking-at "foo") 
(delete-word) 
(delete-white-sides) 

else (stop-doing)))) 


The (%include e-macros) must be at the beginning of any file that 
uses the Emacs environment Lisp macros. The e-macros.incl.lisp 
file should be in your "translator" search path in order to do 
any Emacs extension development work. 


What this function does in essence is type “A, and as long 
as the first three characters on the line are "foo", does an ESC 
D, followed by ESC \ to remove the whitespace after the word. 
When the first three characters are no longer “foo", it returns. 
The "looking-at" is an Emacs predicate (to be described in detail 
below) that tests whether a given string is to the right of the 
current "cursor". For this function and any others that you 
write, you could set a key as described above (‘XA _ for 
shave-line). 


The code for the foodeleter makes no mention of printing, 
output, or displays because it does not need to. The screen or 
printing terminal is managed automatically by the Emacs 
redisplay. The display need never be thought about in coding 
Emacs extensions. 


USING EMACS REQUESTS IN EXTENSION CODING 

Many of the Emacs requests can and should be used in coding 
extensions, for example, go-to-end-of-line, forward-char, 
go-to-beginning-of-buffer, delete-word and skip-over-indentation. 
Some requests, however, should not be used in extension code. 
For example, if you want to search for some string, you do not 
want to invoke string-search (“S), since that prompts the user in 
the minibuffer for a search string. The following table lists 
some important keystroke requests whose command names you should 


Ss 
not use and gives alternative functions to use. 
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KEY DO NOT USE USE INSTEAD 


AN next-line-command next-line 
The next-line-command function is unnecessarily 
expensive in considering screen position, and handles 
numeric arguments. The next-line function always goes 
to the beginning of the next line. 


AP prev-line-command prev-line 
Same reasons as above. The prev-line function always 
goes to the beginning of the previous line. 


AK kill-lines kill-to-end-of-line 
delete-char (at eol) 
The kill-lines function is complex, has many cases, and 
handles numeric arguments. 


AS string-search forward-search 
The forward-search function takes a string as a Lisp 
argument, does not prompt, moves the cursor if the 
search succeeds, and returns truth or falsity to 
indicate result. 


AR reverse-string-search reverse-Search 
Same as “S. 


AX“R read-file read-in-file 
The read-in-file function takes a Lisp argument for 
pathname, does not prompt. 


AXAW write- fi] 


Same as “X4R, 


a Lrye 
7 . 


AW wipe-region wipe-point-mark 
Use local marks, see below. 


ESC W copy-region point-mark-to-string 
does not require modifying the user-visible mark or the 
kill stack. 


ESC / regexp~search-command regexp~search 
Same issues as “S. Takes a Lisp argument, no slashes. 
Returns falsity if not found or moves cursor to after, 
and returns mark to before, matched string. Be careful 
to release this mark (see below). 


AXB select-buffer go-to-or-create-buffer 
Takes an argument, does not prompt. 


AXAP find-file find-file-subr 
Takes an argument, does not prompt. 
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AT redisplay-command full-redisplay 
redisplay-current-window-relative 
Two Separate functions, less dealing with numeric 
arguments. 


Requests that accept a positive numeric argument as meaning 
repeat that number of times, e.g., *B, ‘“D, “F, ESC B, ESC D, ESC 
F, #, ESC #, etc., are acceptable in extensions; they do not 
inspect their arguments. They are invoked multiple times by the 
Emacs. listener if appropriate. Requests whose names include the 
word "command” are usually not intended to be used in code. 


The value of a numeric argument, e.g., 5 in ESC 5 “4B, is 
available as the binding of the global variable "numarg"; if no 
numeric argument is given, this variable is set to the symbol 
"nil™ (not to be confused with the global variable nil, whose 
binding is) the symbol nil), which is the representation of 
falsity. 


The normal printing characters are bound to the self-insert 
function, which inserts the last physical character typed at the 
current point in the buffer. This is clearly unusable from code, 
if your desire is to insert text into the buffer. For this 
purpose, the Emacs environment provides the insert~string 
function, whose argument is a string to be inserted into the 
buffer at the cursor. As in typing in text manually, the cursor 
is left after the inserted text: 


(defun make-a-point () 
(go-to-beginning-of-line) 
(insert-string "CASE IN POINT: ")) 


This make-a-point function, when invoked, goes to the 
beginning of the line, and inserts the string "CASE IN POINT: " 
in the buffer. The cursor is left after the inserted string. 


As used here, phrases like, “the cursor is moved around” or 
"a string is inserted" in a function, do not imply that the user 
watching the screen can see all these things happen. No action 
on the screen occurs until the entire function has finished 
running, at which time the screen is updated all at once, showing 
the cumulative effect of what has happened, regardless of how it 
happened. 
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MARKS AND THEIR MANAGEMENT 


Like the cursor, a mark iS a conceptual pointer to the 
position between two characters in the current buffer. Marks 
remain between these two characters regardless of other 
insertions or deletions in the same buffer, even on the same line 
as the mark. Marks are valuable because regions of text in the 
buffer are specified as the extent between the current conceptual 
cursor, (the point), and a given mark. Marks are a type of data 
object in the Emacs Lisp environment, like strings, numbers, and 
Symbols. The value of any variable can be made to be a mark. 
The value of several variables might even be the same mark. The 
words "the-mark" used in Emacs descriptions designate one mark 
that is the value of a global variable that many supplied 
functions know about. Emacs functions use many temporary marks. 


The set-mark, release-mark and wipe-point-mark Functions 


The set-mark function creates a new mark, which points to 
the current point in the current buffer. It stays around, and is 
updated by the editor, any time text is inserted or deleted in 
this buffer. This is expensive, so you must take care to 
discard, or release marks when you are done using them. This is 
done by giving them to the release-mark function. An example of 
a function which deletes three words and everything between them 
follows: 


(defun delete-three-words () 
(let ((temp-mark (set-mark))) smake a mark in 

;a temp var. 

(do-times 3 (forward-word)) ;3 words forward 

(wipe-point-mark temp-mark) ;wipe out the stuff 
;between point and 
swhere point was. 

(release-mark temp-mark) ) ) 


The variable temp-mark is set to a mark representing the point at 
the time delete-three-words is entered. The "do-times" isa 
Special form that repeats the evaluation of one or more forms a 
given number of times. Its syntax is: 


(do-times <HOWMANY> <FORM1> <FORM2> .. <FORMn>) 


The wipe-point-mark is a function that, given a mark, takes all 
the text between point at the time it is invoked and that mark 
(1.e., point at the time that mark was created) and deletes it 
from the buffer. It is pushed onto the kill ring, so that “*Y can 
be used to retrieve it. After the computation, the mark is 
freed, (for better performance). 
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The with-mark Special Form 


The sequence of setting a mark, using it, and releasing it 
is so common that a special construct in the Emacs Lisp 
environment is provided that takes care of all of this, including 
the creation of a temporary variable, so no prog or let is 
needed. It is called with-mark. The delete-three-words 
function, rewritten to use it, looks like this: 


(defun delete-three-words () 
(with-mark m 7m is usually used for the name of a mark 
(do-times 3 (forward-word) ) 
(wipe-point-mark m))) 


The syntax of the with-mark construct is: 


(with-mark <MARKNAME> 
<FORM1> 
<FORM2> 


¢ee 


<FORMn> ) 


It means: "Where I am now, call that <MARKNAME>. Evaluate the 
forms <FORMI> to <FORMn>, sequentially, returning the value of 
the last one as a value. Before returning anything, however, 
free the mark I made." 


Marks allow you to return easily to where you were at the 
time you started something. The following function truncates a 
line longer than 50 print positions, and handles backspaces and 
tabs properly: 


(defun trunc-50 () 


(with-mark m sremember where you started 
(go-to-end-of-line) 
(if (> (cur-hpos) 50.) sdot is for decimal 


sdefault is octal 
(go-to-hpos 50.) 
(kill-to-end-of-line)) :what “K does at not e.o.l. 
(go-to-mark m))) sreturn to where you were 


A function that tells you the horizontal position (ona 
dprint, not on the screen) of the current point is cur-hpos (the 
left margin is considered to be 0). It takes no arguments. The 
function go-to-hpos moves point to a position on the current line 
whose horizontal position is its argument. If the line is 
shorter than that horizontal position, the point gces to the end 
of the line and go-to-hpos returns nil. Otherwise, if it 
Succeeds in moving point to the specified position, it returns 
the number gone to. Thus, this function can be used asa 
predicate. Therefore, the "if" in the above example could 
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instead be: 


(if (go-to-hpos 50.) 
(kill-to-end-of-line) )} 


The "(go-to-mark m)" above tells the editor to move the 
current point in this buffer to the point where it was at the 
time the mark called "m" was created. 


The save-excursion Special Form 


Although moving the editor's point to previously saved marks 
is extremely useful, you often use marks simply to return to the 
Place where you were before you began a sequence of requests. 
This case is so common that a special mechanism is provided just 
for this: it is called save-excursion, and it takes care of all 
the problems of temporary variables and releasing the mark when 
done. The sample function trunc-50 recoded to use save-excursion 
looks like this: 


(defun trunc-50 () 
(Save-excursion 
(go-to-end-of-line) 
(if (> (cur-hpos) 50.) 
(go-to-hpos 50.) 
(kill-to-end-of-line)))) 


The save-excursion special form does the following: remembers 
where you are, via a mark saved in an internal variable, 
evaluates all of the forms within the save-excursion, and returns 
as a value the value of the last one. Before returning anything 
however, it moves the editor point back to where it was when the 
Save-excursion was first entered, and releases the mark used to 
remember this place. 


If point were at print position 75 at the time trunc-50 was 
called, it winds up at position 50, even though the mark to which 
it wants to return points to what was at position 75. No error 


ar? 


is indicated, or has occurred. Marks remain even if characters 


The special form, save-excursion-on-error, is used in the 
same way aS Save-excursion. It returns to the original point 
only if an error occurs while executing the functions. : 
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Most. Emacs functions that delete text from the buffer save 
the text on the kill ring. Functions that you define that use 
these standard functions (such as delete-three-words, above), 
therefore, also save the deleted text. 


To prevent deleted text from being saved, wrap the code that 
will delete text in the without-saving special form. For 
example: 


(without-saving (wipe-point-mark m) ) 


deletes all the text between the current point and the position 
designated by the mark m without saving it on the kill ring. Any 
text deleted by an internal deletion primitive while the code 
contained within a without-saving special form is executing will 
not be pushed onto the kill ring. 


The without-modifying special form is Similar to 
without-saving. It is used to enclose code that deliberately 
modifies read-only buffers, such as those used by the directory 
and buffer editors. For example: 


(without-modifying 
(go-to-beginning-of-line) 
(delete-char) 
(insert-string "XK")) 


might appear in a menu-type editing subsystem within Emacs to 
change the space at the beginning of some line to an X when the 
user selects an object for deletion. 


Text can be explicitly pushed onto the kill ring by the 
killsave-string function. It takes a single argument, which is a 
Lisp string or symbol, and pushes it in the usual way onto the 
top of the kill. cing. 
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Other functions which interface to the kill ring include 
kill-ring-top, kill-pop; and rotate-kill-ring. The kill-ring-top 
function returns the first item on the kill ring (as does “*Y)}. 
The kill-pop function returns. the first item on the kill ring and 
rotates the kill ring (as does ESC Y). The first item becomes 
the last item, the second item becomes the first item, and so on. 
The rotate-kill-ring function just rotates the kill ring. 


CLEANUP HANDLERS 


You may have wondered, in the previous section, what happens 
if an extension encounters an error while executing, and never 
gets to release a mark it has. set. When errors occur (for 
example, moving past the end of the buffer), Emacs aborts 
execution of request functions, returns to its listener, and 
beeps (as when a “G is performed). 
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The unwind-protect Special Form 


Since the releasing of marks is important, a facility like a 
cleanup-handler is needed to make sure that marks get released 
when code is aborted. There is such a facility in Lisp that is 
useful for many other things, too: save-excursion returns the 
cursor to the point at which it found it if aborted through; 
Save-excursion-buffer returns to the buffer where it found the 
editor if aborted through; all the mark-handling forms release 
their mark, and so forth. These Emacs-environment primitives use 
the cleanup~handler facility internally, so you need not worry 
about cleanup-handlers if you use them. However, occasionally 
(see the code for columnating the Emacs wall chart, for example) 
you must use cleanup-handlers explicitly. The Lisp form 
unwind-protect is the primitive cleanup-handler. Its syntax is: 


(unwind-protect 
<SUBJECTFORM> 
<CLEANUPFORMI> 
<CLEANUPFORM2> 


<CLEANUPFORMn> ) 


The <SUBJECTFORM> is evaluated, and then <CLEANUPFORM1> to 
<CLEANUPFORMn> (any number of cleanup forms are permissible), and 
the value of the <SUBJECTFORM> returned. So far, unwind-protect 
is much like prog2 or progn. The difference, however, is that 
<CLEANUPFORMi> to <CLEANUPFORMn> are executed even if the 
execution of <SUBJECTFORM> fails and aborts. Similarly, the 
cleanup forms are executed even if things like a return from a 
prog inside the <SUBJECTFORM> causes its execution to terminate 
prematurely. 


Thus, the cleanup forms are executed after every termination 
of the <SUBUJECTFORM>, whether normal or abnormal. The following 
use of unwind-protect (which could be done in simpler ways, but 
is here for illustrative purposes) performs "complex-function", 
and returns the cursor to the beginning of the buffer, even if 
"complex-function" explodes: 


(unwind-protect 
(complex-function) 
(go-to-beginning-of-buffer) ) 


If you want more than one <SUBJECTFORM>, you should use progn to 
encompass them, and make your <SUBJECTFORM> this progn. 


Unlike Multics PL/I cleanup handlers, unwind-protect cleanup 
forms are executed upon normal termination of the subject forn, 
too. 
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, 


The protect Special Form 


The e-macros special form, protect, can be used in place of 


unwind-protect. Its syntax is: 


(protect FORM1 FORM2 FORM3 FORM4... 
&always CLEANUP1 CLEANUP2... 
&success. SUCCESS1 SUCCESS2.... 
&failure FAILURE1 FAILURE2....) 


where: 

FORMi 
are forms to be evaluated. 

CLEANUPi : 
are forms to be evaluated after the FORMs, whether or 
not an error occurs in evaluating the FORMs. 

SUCCESSi 
are forms to be evaluated only if no errors occur in 
evaluating the FORMs. 

FAILURE1 


are forms to be evaluated only if an error does occur 
in evaluating the FORMs. 


Any of the clauses &always, &success, or &failure can be omitted. 
Forms that were written using unwind-protect, e.g., 


(unwind-protect (progn FORM1 FORM2...) 
CLEANUP1 CLEANUP2...) 


can now be written using protect as follows: 


(protect FORM FORM2...&always CLEANUP1 CLEANUP2...) 


USEFUL PREDICATES 


The following predicates in the Emacs environment are basic 
to all extension-writing; they are used to test various 
hypotheses about point, marks, and the buffer: 


(eolp) 
End of line predicate. True if point is at end of a 
text line right before the newline character. 
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(bolp) 
Beginning of line predicate. True if point is at the 
Start of a text line, either before the first character 
of the buffer, or after a newline. 


(firstlinep) 
First line predicate. True if point is on the first 
text line of the buffer. 


(lastlinep) 
Last line predicate. True if on last buffer line, 
which is the line after the last newline character, if 
there is one. 


(at-beginning-of-buffer) 
True if point is right before the first character in 
the buffer. 


(at-end-of-buffer) 
True if point is right before the newline on the last 
line of the buffer. You cannot go past it. 


(looking-at <STRING-VALUE> ) 
True Lf <STRING-VALUE> appears in the buffer 
immediately to the right of point. Restriction; 
<STRING-VALUE> can not contain a newline character, 
except as its last character. 


(at-white-char) 
True if the character to the right of point is a space, 
newline, or tab. 


(point>markp <MARK>) 
True if the current point is further in the buffer than 
the position defined by <MARK>. This is expensive, and 
should not be used casually in loops. 


(mark~reached <MARK>) 

True if the current point is up to or beyond <MARK> in 
the buffer. Intended for use in controlling 
character-by-character loops; it expects that point 
Starts to the left of <MARK> and moves toward it. The 
function (order-mark-last <MARK>) can be used to switch 
point and mark if needed at the start of such loops. 
Does not terminate unless executed with mark and point 
on same line. 


(mark-at-current-point-p <MARK>) 


True if the mark <MARK> represents the same position as 
the current point. 
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(mark-on-current-line-p <MARK>) 
True if the mark <MARK> represents a position on the 
same line as the current point. 


(mark-same~line-p <MARKi> <MARK2>) 
True if two marks that are arguments represent 
positions on the same line. 


(Lline-is-blank) 
True if current line is all blanks or empty. 


(empty-buffer-p <BUFFER-SYMBOL> ) 
True if the buffer identified by <BUFFER-SYMBOL> is 
empty. The form (empty-buffer-p current-buffer) can be 
used to test the emptiness of the current buffer. See 
below for a discussion of buffer symbols. 


(at <QUOTED-CHARACTER>) : 
True if the character given, e.g., (at "$"), appears in 
the buffer immediately to the right of point. This is 
more efficient than looking-at for single characters. 
Note that: | . 


{at ™ 
™) 


igs equivalent to (eolp). Use the latter. (See also 
if-at.) 


(back-at <QUOTED-CHARACTER> ) 
Same as at, but deals with the character to the left of 
the current point. See also if-back-at. 


(null-stringp <STRING-VALUE>) 
True if its argument is a zero-length string ora 
symbol with the zero-length printname. 


(yesp <STRING-VALUE>) 
Asks the user a yes-or-no question in the minibuffer, 
namely, <STRING VALUE>; accepts yes, y, no, orn as 
answers and returns true if response is affirmative. 
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This function that trims from the left (ltrims) all the 
lines in the buffer demonstrates the use of these predicates: 


(defun ltrim-ali-lines () 


(Save-excursion sbe polite, restore point 
(go-to-beginning-of-buffer) 
(do-forever sloop on lines thru buffer 
(do-forever sloop thru chars on line 
(if (eolp) (stop-doing) ) ;stop at eol. 
(if (at-white-char)(delete-char) ;do the work 
else (stop-doing))) snon-white char, next line 
(if (lastlinep) (stop-doing));quit when did last line 
(next-line)))) ;leaves you at b.o.l. 


WHITESPACE MANAGEMENT 


Neatly formatted editor output and displays, as well as 
program and document formatting, require good whitespace 
management. The following functions exist to deal with 
whitespace: 


skip-over-whitespace 
Takes no arguments. Moves point forward over all tabs, 
blanks, and newlines until a non-white character or the 
end of the buffer is reached. 


skip-back-whitespace . 
Takes no arguments. Moves point backward over all 
tabs, newlines, and blanks until the character to the 


left of point is none of these, or the beginning of the 
buffer is reached. 


skip-to-whitespace 
Moves forward until character to right of point is tab, 
blank, or newline. Since last character in buffer must 
be a newline, there is no special end condition. 


skip-back-to-whitespace 
Moves backward until the character to the left of point 
is a tab, blank, or newline, or the beginning of the 
buffer is reached. 


delete-white-sides 
Deletes leading or trailing blanks from anything, or 
deletes space between words. 


skip-over-whitespace-in-line 
Same as skip-over-whitespace, but stops before the 
newline character at the end of the line (i.e., stops 
at the end of the line) if it gets that far. 
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skip-back-whitespace-in-line 
Same as skip-back-whitespace, but does not proceed 
backward beyond the beginning of the line. 


You often need to generate whitespace to reach a given 
horizontal position (column), for tabbing and page layouts. The 
function whitespace-to-hpos performs this service; it generates 
tabs and spaces as appropriate, moving point until the horizontal 
position that is its argument is reached. The following function 
moves. all lines in the buffer seven spaces over, regardless of 
their original indentation, with the right amount of tabs and 
spaces: 


(defun move-over-7 () 
(save-excursion 
_(go-to-beginning-of-buffer) sall do-for-all-lines 
(do-forever sstart like this. 
(skip-over-indentation) ;This is ESC M 
(let ((hpos (cur-hpos) )) 
z;let hpos be the curr. pos. 
(delete-white-sides) | 
;close up all original space 
(whitespace-to-hpos (+ hpos 7))) 
;make just enough 
(if (lastlinep) (stop-doing) ) 
(next-line)))) 


A related need is to space to a given position, leaving a 
single space if you are already there or beyond. This is useful 
for producing columnar output where overlength fields must be 
separated (as AXAB does in its local display). The 
whitespace-to-hpos does not do this; it stops if it is far 
enough. However, format-to-col takes a single argument, a 
horizontal position to be spaced to. If the current point is 
already that far, it inserts a space. 


EXTRACTING TEXT FROM THE BUFFER 

The function point-mark-to-string gets a Lisp string whose 
value is the string of characters between point and the mark that 
is its argument. To demonstrate, a function that finds a 
vertical bar (|) ona line, deletes it, and swaps the two 
line-halves around it is defined below. For instance, the line: 


An Indian with a zebra | never trips in the snow 
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The function is: 


(defun swap-around-bar () 
(go-to-beginning-of-line) 
(if (not (forward-search-in-line "|")) _ scheck for one 
(display-error "Hey, there is no ""{""!")) 
(rubout-char) swhat # does 
(with-mark m sm in middle of line 
(go-to-end-of-line) 
(let ((temp (point-mark-to-string m))) ;get 
smiddle 
;to end 
(without-saving (wipe-point-mark m)) 
(go-to-~beginning-of-line) 
(insert-string temp)))) ;put in text 


The forward-search-in-line is just like forward-search, except 
that it indicates failure if it cannot find its search string in 
the current line. If the vertical bar is not found, 
display-error lets you know and does a command-quit, (4G), which 
stops the execution of this function.at once and returns to Emacs 
command level (see below). This is useful by itself to search 
for some string only in a given line. There is also a 
reverse-Search-in-line, and a’regexp-search-in-line, which are 
Similar in their relation to “R and ESC /. 


TALKING TO THE USER 


You cannot use the Lisp 1/0 system to print out messages 
and/or query the user. The Emacs redisplay manages the screen 
itself, entirely. Thus, you can not use "print", or "read", or 
other Lisp functions that you may be familiar with. 


A function called minibuffer-print prints all the messages 
that Emacs outputs in the minibuffer screen area. It takes any 
number of arguments, which must be strings. The function 
decimal-rep is provided to convert numbers into strings for 
inserting them in the buffer or handing them to display-error. 
The following function counts the number of As in the current 
line: 


(defun a-counter () 
(let ((n 0)) sinitial count 
(save-excursion swhy not? 
(go-to-beginning-of-line) 
(do-forever 
(if (not (forward-search-in-line "A")) | 
(minibuffer-print "Found " (decimal-rep n) "As.") 
(stop-doing) ) 
(setq n (+ 1 n))))) scount them. 
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The forward-search-in-line leaves the point to the right of 
what it finds (like “*S), so that it does not find the same 
occurrence the next time. 


To prompt the user for input in the minibuffer, use the 
function minibuffer-response. It takes one, two, or three 
arguments. The first argument is the prompting string. The 
second is the character to be used to terminate minibuffer input. 
It can be either ESC or NL; if not supplied, NL is the default. 
If the value of ESC is used, minibuffer input terminates on an 
ESC. If the value of NE is used (NL, not CR), minibuffer input 
terminates on a carriage return. The third argument, when used, 
is a string to be inserted as the user's response. The user can 
edit this string. Thus: 


(minibuffer-response "Type new division name: ") 


returns the user's response to this question when he terminates 
it with a carriage return. The value of minibuffer-response is a 
Lisp string. The carriage return does not appear in it, nor does 
the prompt. | 


The minibuffer-response function sets a variable called 
last-minibuffer-response. Te the ESC x opt 
remember-empty-response option is set off (it is on by default), 
last-minibuffer-reponse is not set to blank when a blank response 
is given. 


To display an error message in the minibuffer and then abort 
execution of an extension, i.e., execute a command-quit (4G), use 
display-error. The display-error is like minibuffer-print, 
except that it does not return, but aborts to Emacs top level 
immediately after printing its error message in the minibuffer. 
Like minibuffer-print, it takes any number of string arguments. 


You can clear out the entire minibuffer with the 
minibuffer-clear-all function. It takes no arguments. 
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Message Printing Functions 


Messages printed by minibuffer-print are suppressed during 
keyboard macro execution, just as search strings are not 
displayed, and other gratuitous messages are suppressed. The 
following set of functions describes the repertoire of 
message-printing: 


display-error 
Prints a message in the minibuffer and aborts to editor 
top level. It is intended for use in error message 
printing. 


display-error-noabort 
Prints a message in the minibuffer and continues 
execution. This function is intended for reporting 
nonfatal errors such as "User not accepting 
messages...”. 


minibuffer-print 

7 Prints a message in the minibuffer, but not during 
macro execution. This function is intended for use by 
extensions that print messages in the normal process of 
their execution, such as the line count from “X=. For 
this function, as well as the others below, in 
multiline minibuffer situations, an appropriate line is 
chosen based upon availability of empty lines and 
several other criteria. 


minibuffer-print-noclear 
Prints a message in the minibuffer (not during macro 
execution), but does not eraSe the previous contents. 
Output 1s appended to the last minibuffer line used. 


display-com-error 
Prints a message in the minibuffer and aborts to editor 
top level. Its first argument is a Multics standard 
error code. Its remaining arguments are character 
strings or symbols. See "Multics Error Table" below 
for the technique used to get error_table_ values into 
your program. 


display-com-error-noabort 
Prints a message in the minibuffer and continues 
execution. Its first argument is a Multics standard 
error code. 


minibuffer-clear 
Clears out the last minibuffer line that was written, 
except during macro execution. This function should be 
used to clear out minibuffers written in by 
minibuffer-print and minibuffer-print-noclear at the 
end of subsystem invocation. 
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display-error-remark 

Identical to display-error-noabort, except that the 
particular minibuffer line on which this remark is 
printed becomes the next one overwritten for any 
minibuffer remark or output. This function should be 
used for transient remarks (such as "Writing", 
"Modified", etc.), that you wish to remove from the 
screen as soon as possible. 


command-quit 

Aborts to top. level (or to the minibuffer if one is 
being entered) and rings the terminal bell. Execution 
of the current extension code is irretrievably stopped. 
This function is used by display-error and 
display-com-error internally; since it is better to 
print a message when an error occurs, generally use 
these latter two functions instead of command-quit. Do 
not use command-prompt-abort (what “G invokes) to error 
abort out of code, since it would abort minibuffers as 
well. 


ring-tty-bell . 
Rings the terminal bell (or beeper) with no other 
effect. All error aborts out of code, such as those 
caused by display-error and display-com-error, do this 
by default. 


VARIABLES 


Many groups of Emacs requests need global variables to 
communicate among themselves and the functions they call. A 
global variable is a Lisp variable that is not the parameter of 
any particular function; its value can be accessed or set by any 
function. Some of the global variables in Emacs are highly 
user-visible, for example, "fill-column", which contains the 
column number of the fill column as set by ‘“XF, and used by the 
filling requests and fill mode. Similarly, the character string 
that is the comment prefix is the binding of the global variable 
"comment-prefix". Extensions often need global variables to 
communicate among their parts. 


Normally, global variables in Lisp are accessed just like 
other variables, i.e., those that are parameters of functions or 
prog or let variables. For instance, a function to set the fill 
column to 30 if it is over 40, might contain the code: 
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When a global variable is used in your program, say one 
named "my-global", the "declaration" 


(declare (special my-global)) 


must appear in the program before its first use, to tell the 
compiler about this "Special" variable (the Lisp term for a 
global variable). The e-macros include file declares many of the 
provided global variables, which you need not declare. 


defvar 


An even more powerful way to declare your own global 
variables is provided by the defvar declaration/special form. In 
its simplest form: 


(defvar my-global) 
is equivalent to: 
(declare (special my-~global)) 


but is simpler and more mnemonic. 


Use defvar to specify an initial value to be assigned to the 
global variable at the time the program is loaded. This value 
will be assigned only if the variable has not already been 
assigned a value; this makes it ideal for user-settable options. 
For example: 


(defvar magic-mode-debug-flag nil) 


not only declares magic-mode-debug flag special, but gives it a 
value of nil (remember that the binding of the variable nil is 
the symbol nil) if the user has not assigned a value to it before 
loading the magic-mode program, where this declaration presumabl 
appears. 7 


PROVIDED GLOBAL VARIABLES 


You have already encountered some of the global variables in 
Emacs during the introduction to Lisp; for example, the global 
variables t and nil that contain the standard indicators of truth 
and falsity. There are also global variables whose values are 
symbols whose printnames (see "Character Dispatching") are 
hard-to-type characters. Most of the interesting global 
variables in Emacs are associated with given buffers, such as 
variables containing the pathname and comment column (this is 
discussed below). 
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There are, however, a few truly global variables that Emacs 
uses. Here are two of them you might need to use. You need not 
declare them special, since they are declared in the e-macros 
include file. 


env-dir 
a string that is the pathname of the directory 
containing all the Emacs library programs. 


process-dir 


a string that is the pathname oof your process 
directory. 


Per-Buffer Variables 


The global variable situation is complicated by the fact 
that editing activity is usually local to each buffer. That is, 
if a set of global variables contains a set of values about what 
is being edited, it usually pertains to what is going on in only 
one editor buffer. I£ you switch to a different buffer, and use 
the same editor facility, you do not want to use or change the 
values of those global variables that pertained to activity in 


rha Arkhar buffer 
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variables unusable, because all functions would have to keep 
track of what buffer they are talking about before using any 
global variables, and therefore maintain several sets of them. 
Fortunately, it is a lot easier than that. The buffer-switcher 
in Emacs saves and restores values of global variables as buffers 
are switched, if you tell it what variables you want so saved and 
restored, when the buffer you are operating in is exited and 
reentered, respectively. Such a variable is called a per-buffer 
variable, and the act of telling the buffer-switcher about it, 
thereby associating its current value with this buffer, is called 
registering it. Once a variable has been registered in a given 
buffer, the functions that use it can assume that its value will 
be what it last was in that buffer whenever the editor enters 
that buffer. Another term for a per-buffer variable is a local 
variable. The following two primitives exist for registering 
local variables; there are no primitives for setting or 
retrieving their values, because the whole point of this 
mechanism is to allow them to be accessed as normal Lisp 
variables. 


register-local-variable 

Called with one argument, the symbol whose name is the 
name of the local variable you wish to register. 
Registers it in the current buffer, if not already 
registered there, and the variable initially inherits 
its "global value". I£ registered, its value is left 
alone. If it has no global value, it acquires the 
Symbol "nil" as its value if this is its first 
registration in this buffer. 
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establish-local-var 
Just like register-local-variable, but takes a second 
argument, a default value to be initially assigned to 
the variable the first time it is registered in this 
buffer, if it has no global value. 


The global value of a per-buffer variable is the value it 
has in buffers in which it is not registered. It is this value 
that is set if you set this variable while ina buffer in which 
it is not registered. A local variable "inherits" its global 
value when it is first registered in a given buffer. For 
variables that have no global value (i.e., were never assigned 
one), establish-local-var can be used to provide default 
initialization. 


EXAMPLE OF LOCAL VARIABLES 


Three functions that maintain a "problem count" in a given 
buffer are started up by typing ESC X monitor-problems CR. Once 
Started, use “XP to count a problem, and “XR to report the number 
of problems noted: 


(defun monitor-problems () scommand-level function 
(set-key ‘AXP 'note-a-problem) ;set the keys needed, 
(set-key '“XR 'report-problems) ;only in this buffer 
(establish-local-var 'problem-count 0)) sregister the 

slocal var, initial value 0O here. 


(defun note-a-problem () sexecuted on “XP 
(setq problem-count (+ 1 problem-count))) sIncrement the 
;variable 
(defun report-problems () ;on “XR 


(minibuffer-print "There have been " 
(decimal-rep problem-count) 
" problems in this buffer.")) 


By calling establish-local-var on the symbol 
"problem-count", the programmer here has ensured that the 
problem-counts in each buffer in which he counts problems will be 
maintained separately. 
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REGISTERED VARIABLES 


The following per-buffer variables are automatically 
registered by the editor. Their values can be inspected or set 
in extension code. 


buffer-modified-flag 
Contains t or nil, indicating that this buffer has or 
has not been modified since last read in or written. 
Set automatically by the editor. Modification of a 
buffer executed within the special form: 


(without-modifying <formi><form2>...<formn>) 
does not set this flag. . 


read-only-flag 

Contains t or nil indicating whether or not this is 
read-only buffer. The editor does not set this flag; 
it is set only by extensions. An attempt to modify the 
text in this buffer produces an error and a quit to 
editor command level if this flag is on and 
buffer-modified-flag is off (nil). The buffer can be 
modified, however, by functions executed from within 
extension code within a "(without-modifying ...)*. 


fpathname 
Contains the full Multics pathname associated with this 
buffer by the last file read or written into/out of it, 
or by find-file. It is nil if there is none. Changing 
it from extension code modifies or "forgets" the 
pathname as you set it. 


der-wahrer-mark 
Contains the mark associated with the user-visible mark 
that “X*X and other related requests see. Is nil if 
the user set no mark in this buffer. Do not set this 
variable; call set-the-mark to do so. 


current-buffer-mode 
Contains the major mode in effect in this buffer. The 
value is a symbol. To state that a major mode of your 
construction is in effect in a buffer, simply set this 
variable. 


comment-column 
Contains the comment column, measured from 0. 


comment-prefix 
Contains the string, which can be a null string, that 
1s the comment prefix. 
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tab-equivalent 
Contains the number of spaces for a tab. Initialized 
to 10., the Multics standard, this can be set. either in 
code or by ESC ESC to edit code from other operating 
systems. The redisplay obeys this variable too, but 
not in two-window mode. 


buffer-minor-modes 


Contains the Lisp list of symbols representing the 
minor modes in effect in this buffer. 


MODE HOOKS 


Emacs provides a set of global variables called mode hooks. 
Most major modes currently have mode-hook variables. The 
mode-hook variable for a major mode allows a user to run his own 
code every time a certain major mode is entered. For instance, a 
user might want to set certain key bindings every time he uses 
PL/I mode. The mode-hook variable is generally named 
XXX-mode-hook for XXX mode. The following are currently defined: 


MODE. NAME OF HOOK VARIABLE 
RMAIL rmail-mode-hook 

MAIL mail-mode-hook 

PL/I. pli-mode-hook 

FORTRAN fortran-mode-hook 

ALM alm-mode-hook 

LISP lisp-mode-hook 

LDEBUG ldebug-mode-hook 

TEXT text-mode-hook 


To use the mode hooks, write a function that is to be 
executed every time the mode is entered, (This function is 
usually defined in the Emacs start_up.) For example: 


(defun Mike-pli-mode-hook() 
(set~key "ESC-+" 'search-for-journalization-notice) ) 


In the start_up, set the variable pli-mode-hook to the symbol 
Mike-pli-mode-hook. This is done with a statement of the form: 


(setq pli-mode-hook 'Mike-pli-mode-hook ) 
Thus, every time Mike enters PL/I mode, the function 


Mike-pli-mode-hook is run, binding ESC + to Mike's 
journalization-notice finder. 


Modes use defvar to assign nil to their mode-hook variables 
if the user (via his start_up) has not assigned something else. 
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Other User Hooks 


Several additional hooks for functions to be called at 
special times are available. In order to use them, write your 
own function, of one argument, and use setq to set the 
appropriate hook to the name of your function. The one argument 
passed is the name of the hook being invoked. These include: 


buffer-creation-hook 

called when a buffer is created. 
buffer-destruction-hook 

called when a buffer is degteoyed: 
buffer-entrance-hook 

called when a new buffer is selected. 
buffer-exit-hook 

called when a buffer is left. 
close-line-hook 

called when the user moves to another line. 


LARGE SCALE OUTPUT 


Output of multiline information, or information longer than 
about 60 characters, should not be done via minibuffer printing, 
but. via the locai-display, or printout facility. This is the 
facility with which buffer listings, global searches, apropos, 
and other requests display their output. On video terminals, it 
displays lines at the top of the screen, asking for "MORE?" as 
each screen fills up. At the end of the local display, it waits 
for the user to type the next Emacs request, and then restores 
the screen. On printing terminals, the data is simply printed 
line by line, with no "MORE?" processing or pausing at the end. 
The local display facility is an integral part of the Emacs 
redisplay. 


Three functions used in generating local displays are: 


init-local-displays 
Is called with no arguments to start a local display. 
Tt sets up the necessary redisplay mechanism, 
initializing it to the top of the screen. 


local-display-generator 

This function is called with a string, whose last 
character must be a newline, and displays it as the 
next line (or lines, if continuation lines are 
required) of local output. If you do not havea 
newline at the end of your String, calling 
local-display-generator-nnl instead provides one 
automatically. There must be no embedded newlines in 
Strings for local output. A null string causes an 
empty line. 
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end-local-displays | 
Finishes a local display, restoring the screen. Causes 
the next redisplay to be suppressed, so the local 
display remains visible on the screen. 


The sequence of calls: 


(init-local-displays) 

(local-display-generator{-nnl} ...) ;perhaps many 
;times 

(end-local-displays) 


correctly produces a local display. 


The best way to generate a well-formatted local display is to 
set up a temporary buffer (see "Manipulating Buffers" below), 
build some text in it, and display its content, in part or in 
whole, as a local display. Three functions are provided to 
facilitate this: 


local-display-current-line 
Does a local-display-generator on the current editor 
line in this buffer. 


display-buffer-as-printout 
Does an init-local-displays, and displays all lines of 
the current buffer as local output. It does not do an 
end-local-displays; you have to do that yourself, 
hopefully after you have gotten out of your temporary 
buffer and cleaned up whatever else you had to. 


view-region-as- lines 
Displays the entire point- to-user-visible-mark as local 
display, making all the necessary calls, including 
end-local-displays. 


While in a function that has a local display in progress, 
you must never call the redisplay (see "Calling the Redisplay” 
below), or call minibuf-response or any other function that 
causes redisplay, for that instantaneously restores the screen 
contents to the windows on display, obliterating the local 
display in progress. 
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The following function locally displays all lines in the 
buffer that contain the string "defun": 


(defun look-for-defuns() suse ESC X look-for-defuns CR 
(save-excursion sremember where you are. 
(go-to-beginning-of-buffer) 
(init-local-displays) ;set up for printout. 
{(do-forever ;loop the buffer 
(1£ (forward-search-in-line "defun") ;look for 
;"defun" | 
(local-display-current-Line) ) scause printout 
sof it 
(if (lastlinep) (stop-doing)) ;check for EOB. 
(next-line))) >Go to start of 
snext line 
(end-local-displays) ) swait for user, and 


;next request 


A special form, display-as-printout, is available. It 
generates a new buffer, executes your contained forms, displays 
the whole buffer as local display, destroys the buffer, and 
returns. Its syntax is: 


(display-as-printout 
<FORM1> 
<FORM2> 


* 


<FORMn> ) 


MANIPULATING BUFFERS 


Often, the easiest way to do string processing in the editor 
environment, i.e., handle strings, catenating, searching, etc., 
is to use the primitives of the editor itself, since it is a 
String-processing language. To do this, temporary buffers are 
necessary. To create a buffer, you should use the primitive 
go-to-or-create-buffer (what “XB uses), which goes toa buffer 
associated with the symbol you give it as an argument. 


Most symbols are kept in a registry: this registry is 
called the obarray, and there is only one symbol of any given 
Mame in it. A symbol registered in the obarray is said to be 
interned. Only one interned symbol named "joe" exists, but you 
can create many uninterned symbols named "joe". If you refer to 
a symbol named "joe" in a program, however, by saying "'Jjoe", you 


always get the interned one. 
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A major feature of symbols in Lisp is that they can be given 
properties, arbitrary user-defined attributes. These attributes 
are catalogued “in” the symbol via indicators, symbols that 
indicate what property you want. The Lisp functions "putprop" 
and "get" store and retrieve properties. 


(putprop 'Fred 'blue ‘eyes) ;Gives the interned symbol 
snamed "Fred" an "eyes" 
;property of “blue”. 


(get 'Fred 'eyes) ;retrieves the property under the 
;indicator "eyes", and thus returns 
;the interned symbol "blue". 


In Emacs, symbols represent buffers. All of the information 
associated with a buffer is catalogued as properties of some 
symbol whose name is the name of the buffer. Thus, it is 
possible to have two buffers of the same name, which would imply 
that of the symbols representing them, only one is interned. The 
AXB request always uses the interned symbol of the name given; 
that is why you can “XB back to an existing buffer instead of 
creating a new one each time. 


Creating a Temporary Buffer 


To create a temporary buffer, you must first create an 
uninterned symbol, to make sure that you are not going to switch 
to a buffer that is already real. To do this, you give a string 
to be used in naming the symbol to the Lisp cliche: 


(maknam (explodec "A string")) 


The explodec blows the string apart into a Lisp list of 
characters; the maknam builds a symbol out of it. The value of 
this form is the new symbol. You can then go to a (guaranteed) 
new buffer of that name, i.e., 


(go-to-or-create-buffer (maknam (explodec "A string”))) 


and the global variable "current-buffer" will have that symbol as 
its value. A temporary buffer is one that is destroyed 
automatically by the editor upon switching out of it. To make a 
buffer temporary, all you have to do is give the symbol that 
represents it (the "buffer symbol") a "temporary-buffer" property 
of the symbol "t". This can be done by the Lisp form: 


(putprop current-buffer t 'temporary-buffer) 
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(The variable "t™ is always bound to the symbol "t"). Once this 
has been done, you must be careful not to switch out of this 
buffer until you are done with it. If your code involves 
Manipulating many buffers, some of them temporary, you must give 
the temporary buffers their temporary-buffer properties at the 
end of your manipulations. 


~ 


A better way to do this is via the set-buffer-self-destruct 
function. Calling this funetion upon the buffer-symbol, as 
below: . 


(set-buffer-self-destruct current-buffer) 


schedules the buffer for deletion as soon as the buffer is 
exited. Using this, you find out sooner if you mistype this 
function name than if you mistype the temporary buffer property. 


When a new buffer is created, it contains one line, which 
consists of a linefeed only. There are no truly empty buffers in 
Emacs. The predicate empty-buffer-p can be applied to a buffer 
symbol to determine if that buffer is in this state. When 
buffers are switched, all information related to the old buffer 
is stored as properties of the buffer symbol: this includes not 
only the local variables registered in that buffer, but the 
location of point, the user-visible (and all other) marks, etc. 
Thus, when buffers are switched back and forth, the cursor 
retains itsS poSition in each buffer (as can be seen while 
editing), although the redisplay might choose to display a screen 
differently after visiting another buffer and coming back. 


Some applications require making a nontemporary buffer, 
putting some text init, and going back there on occasion. 
Therefore, you might want to go into a nontemporary buffer of an 
interned buffer symbol; 

(go-to-or-create-buffer 'name-and-address-buffer) 


or perhaps keep a global (not per-buffer) variable that you set 
once to an uninterned symbol: 


(setq name-and-address-keep-track 
(maknam (explodec "Name and Address Buffer"))) 


and switch into it by saying: 
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The function buffer-kill can be called with a buffer symbol 
to destroy a buffer. The function destroy-buffer-contents (of no 
arguments) can be called to reduce the current buffer to a single 
"empty" line (buffer contents are not pushed onto the kill ring). 


dont-notice-modified-buffer : 


When you create features and modes that interact with the 
user either by placing "results" in a buffer, accepting user 
input typed "into" a buffer, or both, these buffers will be 
"noticed" when the user leaves Emacs, with the standard query 
about modified buffers. However, you can prevent quit-the-editor 
(what “*X4C invokes) from taking notice of a given buffer even 
though that buffer is modified. This is done by marking the 
buffer concerned with the dont-notice-modified-buffer function. 
It takes a. Single argument, which is the buffer symbol of the 
buffer concerned. 


Variable for Buffer Manipulation 


The following two variables are relevant to buffer 
manipulation: 


current~buffer 
The value of this variable is the buffer symbol of the 
current buffer. Do not change it, or incorrect 
operation results. Use go-to-or-create-buffer. 


previous-buffer 
The value of this variable is the buffer symbol of the 
last buffer, which is returned to when “XB CR is typed. 
It 1S acceptable to setq this variable. 


The go-to-or-create-buffer function accepts a buffer-name of 
"" as meaning go to that previous buffer. 


The save-excursion-buffer Special Form 


The special form save-excursion-buffer is invaluable when 
writing functions that switch buffers. It provides for 
remembering which buffer you were in, and switching back to it 
when you are done. It also saves and restores the state of 
"previous-buffer". The Save-excursion-buffer is like 
Save-excursion; it executes its contained forms while pushing the 
buffer-state of the editor on an internal stack, and returns the 
value of the last form within it. 
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The following program, when invoked after typing somebody's 
Name (say you hook it up to a key), follows it with his title in 
parentheses. Assume the file >udd>FamNam>personnel_ data looks 
like this: 


Washington, G. =Lumberjack 
Duck, D. =Pessimist 
Nietzsche, F. =Existentialist 
Mouse, M. =Optimist 
Eisenhower, D. D.. =Golfer 


(defun insert-person-title () 
(let ({name (save-excursion ysave guy's point 
(skip-back-whitespace) ;get to end of word 
(with-mark m sm = end of word 
(backward-word) ;go to heg. of wd. 
(catenate (point-mark-to-string m) 
"e"))))) 


sreturn the word with a "," after it. 


(insert-string yinsert 
(catenate ™ (" ;O0pen paren and sp 
(save-excursion-buffer ;save the old buff 


(go-to-or-create-buffer 'name-position-records) 
;go to stuff 
(lf (empty-buffer-p current-buffer) ;read it 
sonce 
(read-in-file ">udd>FamNam>personnel data") ) 
(go-to-beginning-of-buffer) ;set up for search 


(do-forever 
(1£ (looking-at name) 


(forward-search "=") 
(return (with-mark n 


sscan lines 

;Ils point at 
>"name,"? 

slook for the =. 
;get to the end. 


(go-to-end-of-line) 
(point-mark-to-string n)))) 
(if (lastlinep)(return "???")) jscouldn't 


(next-Lline) ) 


ED 


sfind him 
smove on 
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This function picks out the name you just typed by skipping 
back over whitespace, and picking up all between there and the 
Start of the previous (current) word. It then inserts, between 
parentheses, the portion of that line of the data file that 
contains the sought name at its front after the equals sign. The 
buffer name-position-records is read into once, and contains the 
data file thereafter. 


The initial save-excursion remembers the user's point 
location while the word is collected. The save-excursion-buffer 
remembers what buffer and where in it all its modes, local 
variables, etc., are, while you operate in the data file buffer. 


The function catenate is a valuable one in the context of 
Emacs; it takes any number of strings (or symbols, whose 
printname will be used), builds a string by catenating them 
first-to-last, and returns it. ~ 


Another useful function in this context is apply-catenate, 
which takes as an argument a list of any number of strings or 
symbols and builds a string by catenating the strings and names 
of the symbols, first to last. 


CALLING THE REDISPLAY 


The Emacs redisplay decides what lines of the curre buffe 
should be shown on the screen, determines how to node the 
current screen to show the contents of those lines, and updates 
the screen in an optimal manner. It is called by the editor 
whenever there is no more input available. It is very simple to 
call. It takes no arguments, i.e., you just Say: 


(redisplay) 


The redisplay does not know or care by what means the buffer 
was modified; if you delete several words with ESC D, “4D, or “W, 
it is all the same to the redisplay, and it acts similarly in 
updating the screen. Normally, the extension writer need not be 
concerned at all about the redisplay. A major feature of Emacs 
is that only the total effect of a complex manipulation is 
displayed, not every small operation that the manipulation used ~ 
to achieve its effect. 
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In some situations, however, it is. advantageous to call the 
redisplay explicitly from extension code. One example isa 
Function that takes a tremendous amount of computer time and 
might wish to update the screen every so often as it finishes 
some major section. You do not tell the redisplay what to 
display or how to display it; it displays some excerpt of the 
current buffer that contains the current line, and shows the 
cursor where the current point is. If you call it during a 
buffer excursion, i.e., while in some special buffer ina 
function, it displays that buffer around its "point". As soon as 
that function returns ta editor command level, the screen is 
overwritten with the original buffer's lines. Thus, calling 
redisplay is. not to be considered a. substitute for local 


displays. 


The most common need. for calling redisplay is in functions 
that add text (or change text) on a line, and move to another 
line. For example, the electric semicolon of electric PL/I mode 
adds a semicolon ta the current line and moves to the next. Ona 
printing terminal, the user would never see the semicolon unless 
Special action were taken. The text in the buffer would indeed 
be right, but by the time the next redisplay occurred (the 
electric semicolon request returned), the editor would be off 
that line, and thus would display the next line, where the 
electric semicolon request left it. While this is correct, the 
printing terminal user looking at his type-in would, with some 
validity, complain that "all the semicolons seem to be missing" 
Thus, the electric PL/I semicolon request calls the redisplay 
immediately after it executes "(insert-string ";")". 


The following is a function for a "card-numbering FORTRAN 
mode", which when invoked (perhaps hook it up to CR) puts a 
sequence number in column 72 (71 from 0) and goes to column 7 of 
the next line. It must call the redisplay so that, on a printing 
terminal, the card numbers get shown: 


(defun fortran-next-line () 
(whitespace-to-hpos 71.) ;go to col 72. 
(insert-string (decimal-rep cardno)) ;cardno is a local 
sbuffer var 


(setq cardno (+ 1 cardno)) sup the next 

scard number 
(redisplay) slet printing 

suser see. 
(new-line) ;get to 

snext line 
(whitespace-to-hpos 6.)) °6 rel = card col 7. 
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Another commonly called redisplay function is 
full-redisplay, of no arguments, which clears and rewrites the 
screen, aS with “L with no arguments. 


Positioning Text on the Screen 


Emacs usually positions text on the screen automatically. 
When the cursor is moved to text already on the screen, it is 
Simply repositioned on the current screen. If the text is not 
already on the screen, Emacs usually centers the line containing 
the text positioned to in the current window. Sometimes, it is 
desirable to have other than this default action. You may wish, 
Say, tO position some text onto the top of the screen from 
extension code; this is what ESC 1 AL does. The 
redisplay-current-window-relative function is what 
redisplay-command (“L) calls when given an argument. Thus, 


(redisplay-current-window-relative 3) 


redisplays the current window with the current line of the. 
current buffer on line 3 of the window. 


EIS TABLES 


The Emacs environment provides a facility for utilizing the 
sophisticated Multics processor instructions for scanning for 
characters in, or not in, a particular set of characters. These 
operations correspond to the PL/I "Search" and "verify" builtins, 
The word requests operate using these facilities. 


A set of characters is represented by a charscan table, a 
compound Lisp object occupying about 200 words of storage. You 
can get a charscan table by giving a set of characters, as a 
String, to the function charscan-table. It returns a charscan 
table representing that set of characters: 


(setq number-verify-table (charscan-table "0123456789+-") ) 


Functions Using the Charscan Table 


Given such a table, there are a set of functions that can be 
called to utilize it to search for characters in or out of that 
set, backward, forward, whole buffer, or only one line. All but 
‘the last of the following functions take one argument, a charscan 
table representing a set of characters (called S here). They 
return nil (falsity) if they hit the end of the buffer or line 
(as appropriate) without finding what they are looking for. If 
they succeed, they move point and return a truth indication. If 
they fail, they do not move point. 
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search-for-first-charset-line 
Scans current line forward from point. Success is 
stopping to the left of a character in S. 


search-for-first-not-charset-line 
Same as above, but Success is stopping to the left ofa 
character not in S. 


search-back-first-charset-line 
Scans current line backward from point. Success is 
stopping to the right of a character in S. 


search-back-first-not-charset-line 
Same as search-back-first-charset-line, but success is 
stopping to the right of a character not in S. 


search-charset-forward 
Scans the buffer from point to the end of the buffer. 
Success is stopping to the left of a character in S. 


search-charset—backward 
_ Scans the buffer backward from point to the beginning 
of the buffer. Success is stopping to the right of a 
character in S. 


search-not-charset-forward 
Scans the buffer forward from point to the end. 
Success is stopping to the left of a character not in 
S. | 


search-not-charset-backward 
Scans the buffer backward from point to the beginning 
of the buffer. Success is stopping to the right of a 
character not in S. 


charset-member 
A predicate; takes two arguments: a character and a 
charscan table. The character can be a single 
character string, a single-character-named symbol, or a 
numeric ASCII value. Returns true if the character is 
a member of the set of characters represented by the 
charscan table. 


The following function finds the first nonnumeric character 
on the line it is invoked on: 


(defun find-first-non-numeric () 
(establish-local-var numscan-table nil) ;does 
svar exist 
PLE Nits: Liesy. NOt Anat yet, 
char scan-tabl "90123456789")))} 


(if (not numscan-table) 
{setq numscan-table ( 
(go-to-beginning-of-line) 
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(if (not (search-for-first-not-charset-line 
numscan-table) ) 
(minibuffer-print "Line is O.K.!"))) >failure 
sis all are 
sin charset 


OPTIONS 


The Emacs option mechanism provides for user-settable 
sVvariables in the Lisp environment. The only difference between 
an "option" and any other global Lisp variable in the editor 
(basic or extended) is that the options are listed at the 
user-visible level by typing ESC X opt list CR, and can be set or 
interrogated via the opt request. The option mechanism also 
provides for checking that numeric variables stay numeric, and 
that variables restricted to "t" or "nil" as values. stay 
restricted to those values. 


Thus, options can control per-buffer or truly global 
variables; the option mechanism imposes no restraints upon the 
dynamic scope of the variables managed by it. The option 
mechanism also provides for a default global value of variables 
it manages. 


A global variable is registered with the option mechanism by 
invoking the function register-option upon the Lisp symbol that 
represents (has the name of) that variable, and its default 
qlobal value. Tf that value is a number, the option mechanism 
restricts the variable's value to numbers; if it is one of t or 
nil, the option mechanism restricts its values to t or nil (which 
you indicate as "on" or "off"). 


The choice of whether a variable should be made an official 
option or not depends upon whether or not you want the user to 
see it when an "opt list" is done, and whether finer control than 
that provided by the option mechanism over the values assigned to 
it is necessary. It is acceptable to register an option the 
first time some code is executed; only then does it appear in the 
option list. It is usual to have forms invoking register-option 
at "top-level" ina file full of code, i.e., outside of any 
function. Such code is executed when the code is brought into 
the editor environment. 


The following code registers an option describing default 
paragraph indentation, and shows a function that creates a new 
paragraph (that should probably be hooked up to a key). Like all 
Lisp global variables, options must be declared "special" for the 
Lisp compiler (see "Compilation" below): | 
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(declare (special paragraph-indentation) ) ;for compiler. 
(register-option 'paragraph-indentation 10.) ;default is ten 


(defun new-paragraph () 
(new-line) stwo new-lines 
(new-line) 
(whitespace-to-hpos paragraph-indentation)) ;tab out 


By issuing the request: 
ESC X opt paragraph-indentation 5 CR 


You can set the amount of indentation inserted by new-paragraph 
tO. 3% 


NAME SCOPE ISSUES 


All of the functions and variables in the Lisp environment 
are accessible to all functions running in it. At times, this 
can be a problem. When adding your own extensions to the editor 
environment, nothing prevents you from choosing a name for one of 
your functions that happens to be the name of some internal (or 
user-visible) function in Emacs. Occasionally, there may be 
reason to do this deliberately, e.g., writing your own version of 
next-line to do something special. This is dangerous, and not 
recommended. 


In general, you want to make sure that none of your 
functions or variables conflict with those of the editor. The 
best way to do this 1s to choose some set of names that minimizes 
the possiblity of conflict. To achieve this, use capital letters 
anywhere (such as initial capitals) or use underscores in your 
Mames, since almost no Emacs or Lisp system functions have 
leading capitals or trailing underscores. Watch out for the few 
exceptions: error_table , e cline, Rtyo, Rprinc, ItoC, Ctol, 
and the DCTL functions for writing terminal control modules. 
There are a few Lisp system functions with embedded underscores, 
but other than make_atom, it does not hurt if you accidentally 
redefine them. The Lisp compiler also warns you if you attempt 
to redefine a system function. No functions in Emacs contain 
underscores in their names. 


Another technique is to use double hyphens in your names. 
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Another way to avoid name scope conflicts is to prefix all 
of your names ina given package with some prefix indicative of 
the facility that you are trying to implement. For instance, if 
you are implementing a SNOBOL edit mode, you might name your 
functions "“snobol-find-match-string", "snobol-get-branch-target", 
etc. The same holds true for global variable names. This is the 
Standard, recommended, and most mnemonic way. 


You can also be reasonably certain that names constructed 
somewhat whimsically (e.g.,"Johns-special-tsplp-hack", 
"find-third-foo", etc.) will not conflict. 


MODES 


The major and minor mode mechanism of Emacs is a way for the 
user to switch in and out of large sets of key-bindings and 
column settings, and to be informed of this via the mode line. 


Major Modes 


A major mode involves a large body of optional code (e.g., 
PL/I mode), sets up for editing code written in a particular 
language, or sets up buffer for some highly specialized task 
where very common keys (e.g., CR) do nonobvious things (e.g., the 
Message mode buffers of the Emacs message facility). Minor modes 
generally involve the way that whitespace or delimiters are 
interpreted, e.g., fill mode and speedtype mode. 


Although modes can be invoked by explicit user commands, 
e.g., ESC X lisp-mode, modes are usually invoked via find-file 
(AX4F) when a user reads in or creates a program and has elected 
the find-file-set-modes option in his start_up. When you invoke 
find-file with a suffixed file (and with find-file-set-modes 
elected), a check is made to see if a function named XXX-mode 
(where XXX is the suffix) has been defined. If such a function 
has been defined, it is invoked. If not, a check is made to see 
if the symbol XXX has a suffix-mode property; if so, the value of 
this property is a symbol denoting a function to be invoked. 
Thus, a form such as: | 


(putprop ‘ec 'exec-com-mode 'suffix-mode) 
in a Start_up causes all ",ec"™ segments to invoke the 
(hypothetical) function exec-com-mode. The defprop special form 
can be used to eliminate the quotes; thus, 


(defprop ec exec-com-mode suffix-mode) 


has the same effect as the form above. 
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A major mode is set up by a user-visible function called 
"XXX-mode”", where XXX is the name of the mode. This "mode 
function" establishes key-bindings (using set-key), and sets 
columns (e.g., fill-column, comment-column) and prefixes as 
necessary. The mode function establishes the mode by setting the 
per-buffer-variable "current-buffer-mode" to a symbol whose name 
indicates the mode. The name of the symbol appears in the mode 
line when the redisplay is invoked while in this buffer. The 
following function sets up a major mode for editing FORTRAN 
programs: 


(defun fortran-mode () ;the mode function 


(setq current-buffer-mode 'FORTRAN) ;symbol 
sfor mode 
(setq Fill-column 70.) ;set columns 
(setq fill-prefix" ") 7S1x Spaces on CR 
(set-key 'CR 'fortran-new-line) ;set up CR key 
(setq comment-column 0) 
(setq comment-prefix "C ™) sthat begins cmts 


(if fortran-mode-hook 
(funcall fortran-mode-hoock) )) 


The function fortran-new-line is assumed to be one that does 
something appropriate, such as numbering cards. The use of the 
function set-key implies that this key binding (of the carriage 
return key) is local to this buffer, and will be reverted when 


this buffer is exited. 


The above code checks the variable fortran-mode-hook to see 
if it is other than nil and invokes the symbol to which it is 
bound if it is indeed not nil. 


The Lisp primitive funcall is used to call functions that 
are the bindings of variables. It is like calling an entry 
variable in PL/I. The funcall function accepts any number of 
arguments; its first argument is the function you wish to call, 
and its second-through-last (optional) arguments are the 
arguments that are to be supplied to the function being called. 
Consider the statement: 


(setq Z2 (funcall ZX 1 2 4)) 
Suppose X is bound to the symbol +. The effect of evaluating the 
above statement would be to apply + toil, 2, and 4, thereby 


assigning a value of 7to 2. However, were X bound to * 
(multiply), a value of 1*2*4 (i.e., 8) would be assigned to 2. 
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The above code in fortran-mode assumes that 
fortran-mode-hook will be bound to nil if it has not been set by 
the user. Of course, defvar elegantly provides for this. A 
statement such as: 


(defvar fortran-mode-hook nil) 


should appear somewhere in the source of fortran-mode. 


Calling the mode-hook-function should be the last thing done 
by the mode function. 


Minor Modes 


Minor modes are less straightforward. Minor modes such as 
speedtype and fill mode have different actions associated with 
the keys they affect (for instance, all the punctuation keys), 
and the minor modes have to have detailed and specialized 
interaction between themselves. There is no way to generalize 
the interactions between the minor modes; no completely adequate 
solution to this problem has been developed. 


Minor modes are asserted and turned off in a given buffer by 
calling the functions "assert-minor-mode" and "negate-minor-mode"” 
while in that buffer, with an interned symbol that identifies the 
mode (and appears in the mode line). A per-buffer variable 
called buffer-minor-modes has as a value a Lisp list of all the 
Symbols identifying the minor modes in effect in this buffer. 
The Lisp predicate memg can be used to test whether a given 
interned symbol is a member of a list, and thus, whether a given 
minor mode is in effect in the current buffer: 


(memq ‘fill buffer-minor-modes) 


returns a truth indication if fill mode is in effect in this 
buffer; otherwise, it returns ss a (false). Functions 
implementing the actions of keys in minor modes should check in 
this way to see what other minor modes are in effect, and what 
they ought do in that case. 


The global variable fill-mode-delimiters is bound to a Lisp 
list of keys that act as punctuation in many minor modes. By use 
of the Lisp function mapc, all punctuation can be set to trigger 
@ given action, The mapce function takes two arguments, a 
function and a Lisp list; the function is called upon each 
element of the list: 
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(defun no-punc-mode-word-on-a-line-mode-on () ;mode function 
(mape 'word-on-a-line-setter fill-mode-delimiters) ;set 
skeys 

(assert-minor-mode 'word-on-a-line)) ;get in mode line 


(defun word-on-a-line-setter (key) ;key is the key 
(set-key key 'word-on-a-line-responder)) ;set these keys 


(defun word-on-a-line-responder () ;key function 
(delete-white-sides) ;get rid of whitespace 
(self-insert) j;insert the typed character 
(new-Line) ) *start a new line. 


This set of functions establishes a minor mode in which each word 
goes on a Separate line as it is typed. 


CHARACTER DISPATCHING 


Several special forms and functions facilitate the making of 
decisions based upon the identity of the character to the right 
(or left) of the current point. All of these functions and forms 
accept either of two ways of describing characters: either a 
Single-character string (e.g., "."), or a symbol whose name is 
that character (e.g., ‘a, aS 1t would appear in a program). The 
first kind, is called the "string form", and the second kind, 
"character objects”. 


The function curchar, of no arguments, returns the character 
to the right of the current point as a character object (this is 
done for storage efficiency; character objects are unique, while 
strings require allocation). You can test for two character 
objects being the same unique object (or any two objects, in 
general) via the Lisp predicate eq: 


(if (eq (curchar) ‘'a) 
(display-error "You are looking at an ""a"™".")) 


You could do this with the looking-at predicate described 
earlier, but for single characters, looking-at is a lot less 
efficient, in both time and storage. 


You cannot use eq to test if two strings have the same 
characters in them; Lisp strings are not uniquely defined in the 


Same way that symbols are uniquely defined via the obarray. Use 
Samepnamep instead. 
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In order to facilitate the use of special characters (tabs, 
linefeeds, Spaces, quotes, etc.) in this way, several global 
variables have values of the character objects for these 
characters: 


ESC ASCII ESC, Ascii 033. 

CRET ASCII carriage return (Ascii 015) 

NL ASCII newline (linefeed), Ascii 012. 
SPACE ‘ASCII blank, Ascii 040. 

TAB ASCII tab, Ascii O11. 

BACKSPACE ASCII backspace, Ascii 010. 

DOUBLEQUOTE ", Ascii 042. 

SLASH /, Ascii 057, hard to type in Lisp code. 


A (eq (curchar) NL) is equivalent to (eolp). 


A special form to test if the current (to the right of 
point) character is a given character is called if-at: 


(if-at "&" (display-error "You can't have an ampersand here!")) 


Its syntax is the same as if, i.e., yt has one, none, or many 
"then" and/or "else" clauses, separated by the keyword "else" if 
there are any else clauses. However, instead of a predicate, 
if-at takes either a single-character string or a character 
object to be compared to the current character. If the current 
character is that character, the then forms are evaluated, etc. 
The if-at converts the character string to a character object at 
Lisp compile time, if necessary. The specification of the 
character must be a form that evaluates to the character of 
interest (e.g., "a", ‘a, variable-bound-to-an-a): 


(if-at TAB (delete-char) 
(whitespace-to-hpos next-field) ) stab to next field. 


The exact effect (and actual implementation) of if-at is as 
though it were shorthand for: 


Cit. (eq. COUrehar): aca) odes “Switece. Cseeied: 


Similarly, a function called lefthand-char is like curchar 
except that it returns the character to the left of the current 
point; if the current point is at the beginning of the buffer, it 
returns a character object for a newline (which is almost always 
what you want). Similarly, an if-back-at special form exists, 
whose syntax and semantics are identical to if-at, except that it 
deals with the character to the left of the current point. 
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Two special forms for dispatching on the current (lefthand 
or righthand) character are called dispatch-on-current-char and 
dispatch-on-lefthand-char they dispatch upon the character to the 
right and the left of the current point, respectively: 


(declare (special parentable)) ;global variable 
(setq parentable nil) ;done when code is 
sloaded into editor 


(defun count-parens-in-buffer () | 
(if (not parentable) ;if not initialized 


(setq parentable (charscan-table "()" ))) stnie 1c 
{Iet (({leftcount 0)(rightcount 0)) ;init the counts 


(save-excursion sbe nice 
(go-to-beginning-of-buffer) 
(do-forever 
(if (not (search-charset-forward parentable) ) 
slook for ( or ) 
(stop-doing)) ;exit the do 
(dispatch-on-current-char ;see which 
( "(" (setq leftcount (+ 1 leftcount))) 
ae ts (setq rightcount (+ 1 rightcount)))))) 
(minibuffer-print (decimal-rep leftcount) " opens, " 
(decimal-rep rightcount) 
"closes."))) 


The general syntax of dispatch-on-current-char and 
dispatch-on-lefthand-char is as follows: 


(dispatch-on-current-char 
(CH1 . <CHi-formi> 
<CH1-form2> 
<CHi-formn>) 
(CH2 <CH2-formi> 
<CH2-form2> 


eee @@p @ 8 @2 H 2 8 


<CH2-formn2> ) 
(CHk <CHk-formi> 
<CHk-form2> 
<CHk-£ormnk>) 
(else <else-formi> 
<else-form2> 


<else-formn>) ) 
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CHi can be any form that evaluates to a single-character 
String or toa character object. When the current character 
(left or right as appropriate) matches a CHi, all of the 
<CHi-form> in that clause are evaluated sequentially, and the 
value of the last returned as the value of the 
dispatch-on-current-char (nil is returned if there are no 
<CHi-form>). If no CHi matches, the else clause is evaluated as 
though it were a matching clause. The else clause is optional; 
if omitted, and no CHi matches, nil is returned. 


READING CHARACTERS FROM THE TERMINAL 
Some Emacs subsystems, such as query-replace, "read" 
characters from the terminal, without echoing them, and base 
their course of action upon the character read. This is not the 
usual method of causing characters to produce effects; the 
key-binding mechanism (i.e., set-key) is the usual way of causing 
requests to be invoked by the typing of characters. However, the 
extension writer may encounter a Situation where he expects a 
Single character response to some question, and this facility is 
provided. Use this facility carefully: the correct way to 
implement functions like the directory and buffer editors is via 
modes and key bindings, not loops that read characters from the 
keyboard. Similarly, the minibuffer query functions (e.g., 
minibuf-response and yesp) should be used to ask questions. 


The get-char function is provided to read the next input 
character; get-char returns the numeric value of the ASCII 
representation of the character. Bear in mind that the next 
input character may well have already been typed, since input to 
Emacs is treated as a stream of typed characters. Therefore, 
get-char does not return to its caller until a character is 
available. The get-char function also performs the necessary 
services of maintaining the input traces displayed by help-on-tap 
(4_L), .of handling keyboard macros, and of sampling for Emacs 
interrupts, such as those used by the Emacs console message 
system. ; 


The following Lisp functions, of one argument each, are 
provided to convert between numbers representing ASCII values of 
characters, single-character strings, and “character objects" 
(single-character symbols): 


Function Input Output 
ascll number Single-character object 
Ttoc number Single-character string 
Ctol Single-character — number 

string or character 

object 
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Occasionally, programs that read characters from the 
terminal are designed to allow normal Emacs requests: to be 
processed during these operations. This usually takes the form 
of either an “escape character," which means that the next 
character(s) are to be interpreted as a normal Emacs request, or, 
alternatively, the interpretation. of all characters "not known" 
to the program as Emacs requests (the former method is preferred 
since it is much cleaner). 


The process-char function receives as an argument a number 
representing the ASCII value of a single character to be 
interpreted as the first character of an Emacs request, and so 
interprets and executes it (including reading of another 
character if necessary) according to the key bindings in the 
current buffer. 


In principle, the basic loop of Emacs can be expressed as: 


(do-forever 
(process-char (get-char) ) 
(rcedisplay) ) 


This is oversimplified; issues involving keyboard macros add some 
complexity, and the calling of redisplay is suppressed if input 
characters are available. Otherwise, the above code fragment is 
a correct description of the basic action of Emacs. 


PROGRAM DEVELOPMENT 


The editor itself provides many powerful tools for 
developing extension code and testing it while editing it. The 
following is a typical scenario in the development of an 
extension. 


You decide to write an extension. You sit down and think 
about it, and decide to code it. You enter Emacs. You do a “*X*F 
on the shaver.lisp file to go into a new buffer with a proper 
file name and select Lisp major mode (assuming that you have the 
option for find-file-set-modes "on"). Then type the form: 


(S$include e-macros) 


at the top of your file; this is necessary to compile it (see 
"Compilation" below), or to use the ESC X loadfile request, 


described below. The file e-macros.incl.lisp should be in the 
"translator" search rules for your process. For efficiency, put 
a link to it in the directory in which you do Emacs extension 


development. Now begin to type in a function: 
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(%include e-macros) 


(defun shave-line () 
(go-to-beginning-of-line) 


At this point, to type the next line, lining it up with the last 
Lisp form, use the indent-to-lisp request, which is on ESC CR in 
Lisp mode, and the next form automatically indents properly: 


(delete-white-space) ;wrong name given deliberately here 


When typing in Lisp in general, ESC CR (in Lisp mode) indents you 
on the next line the right amount. So, continue with: 
(go-to-end-of-line) 
(delete-white-space) 


Now you are looking at the buffer with the code for 
"shave-line". To try it, load the code in the buffer into the 
editor. ESC “Z in Lisp mode does this. . Immediately, you get the 
message: 


Unbalanced parentheses. 


This means that there were not enough close parentheses 
Somewhere: Emacs could not find the boundaries of the Lisp form. 
Fix the program problem. You are on the last line, so just type 
the close parenthesis: 


(delete-white-space) ) 


Now do the ESC “Z again. The cursor returns'to the function you 
are trying to edit. To see if it works, invoke it from Lisp: 


ESC ESC shave-line CR 


ESC ESC puts parentheses around what you type, evaluates it, and 
types out the Lisp value so returned. However, you find the 
message: 


lisp: undefined function: delete-white-space 


printed in the minibuffer, with the terminal bell rung, so you 
must have the wrong function name. Since you know it is ona 
key, type: 


x 


ESC X apropos white CR 
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and learn about delete-white-sides. Now go to the first line 
that has the bad function name, do an @ to clear the line, ESC “I 
to line up to retype the form, and: 


(delete-white-sides) 
Fix the other baa. Gene, too, and again type: 
ESC ESC shave-line CR 
Surprisingly, it still says: 
lisp: undefined function: delete-white-space 


as though you had not changed anything. Indeed, fixing it in the 
buffer is not good enough. You must reload it into the editor 
environment; use ESC “Z again. Now try it again: 


ESC ESC shave-line CR 


and immediately your function on the screen changes appearance; 
all the whitespace on the ends of the last line of the function 
disappears. It works, but its appearance is messy. This is a 
problem with editing what you are testing: it must either be 
innocuous, i.e., do something harmless, or you must be prepared 
to reconstruct damage your function does, or switch to a test 
buffer before running it. 


Fix your function, and you are almost done. Although it 
exists in an editor buffer, and in the editor Lisp environment, 
you must remember to write it out: 


AKAS 


writes it out to shaver.lisp as you set up for initially. Now 
you have an operative Lisp program that you can use again. If, 
in a future invocation of the editor, you need to use it, you 
type: 


ESC X loadfile <path>shaver.lisp CR 


and get it into the environment. There are two problems with 
this, however: 


Ls Whoever loadfiles must have e-macros.incl.lisp in his 
translator search rules. 


ot a ew 


interpreter in the Lisp subsystem; Emacs is compiled 
Lisp, and compiled Lisp runs up to 100 times faster 
than interpreted Lisp and has fewer problems. 


2. The code is executed interpretively by the Lisp 
ret 


Ww 
! 
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Thus, the file shaver.lisp should be compiled. Then, the 
compiled object segment can be loaded into the editor with: 


ESC X loadfile <path>shaver 


See below for a description of how to compile Lisp programs. 


Coding Problems 

Some other problems are of immediate interest to the 
extension writer. It is possible, and fairly common, to write 
loops that do not terminate, or that generate infinite garbage. 
If you invoke your request, and the cursor never leaves the 
minibuffer, and ‘“G seems to have no effect, you are ina loop. 
Hit QUIT, and use the program_interrupt (pi) Multics command to 
reenter Emacs. If you are singularly unfortunate, you get: 


lisp: (nointerrupt t) mode, unable to accept interrupt 


in which case you are stuck in the process of generating infinite 
garbage. In this case, you must release, and your editing 
session is lost. If you are more fortunate, you will get your 
screen back, with the cursor at the place your function left it. 
Often, by looking at exactly where it left it, you can get a good 
idea of what kind of thing was giving your program a hard time. 


If you get messages from Multics that tend to indicate that 
there is no more room in your process directory, you are probably 
generating an infinite number of lines, i.eé., an infinite buffer. 


Another thing that can happen is you might expose some bug, 
or what you believe to be a bug, in Emacs, or worse yet, Multics 
Lisp. Use the trouble report forwarding mechanism to describe 
what you encountered and why you think it is a bug. 


You can also destroy the editor environment by bad coding. 
This is particularly true in running compiled code that was not 
checked out interpretively (i.e., via ESC “2). Storing into 
"nil" is one common way to do this. If the entire editor seems 
broken, and the redisplay does not even show the screen, this is 
what you have done. Quit and release and start all over again. 


A function called debug-e is called as: 


ESC X debug-e CR 
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It sets "(¥*rset t)" mode and other Lisp debugging aids, and 
unsnaps all "lisp links". It also reverts to native Maclisp 
QUIT/pi handling. To use this, however, you must be familiar 
with the debugging features of Multics Maclisp. 


To get the value of a global variable to be printed out, 
Say, fill-column, type: 


ESC ESC progn fill-column CR 


Be careful, for values typed out are in octal. 


A Lisp code debugging facility within Emacs, called LDEBUG, 
or Lisp Debug mode, allows for the setting of breakpoints, 
dialogue with Lisp within Emacs, tracing, and so forth. See 
Section 4, 


COMPILATION 


All production Multics Lisp programs are compiled. This 
results ina tremendous performance improvement, both for the 
user and the system. Compiled Lisp programs are executed 
directly by the Multics processor; interpreted programs are 
interpreted by the Lisp interpreter. Emacs is compiled Lisp. 


The Lisp compiler is a Multics program that can be invoked 
from command level. It has the names lcp and lisp_compiler. To 
compile a program named myfuns.lisp, you say: 


lep myfuns 


to Multics, and you get an object program named "myfuns", which 
can be loadfiled, in the working directory. 


The compiler diagnoses Lisp syntax errors. It warns you of 
implied special variables (if you did not declare a variable 
Special, and it is not a local variable in the function in which 
it was referenced, you probably made a mistake. All global 
variables should be declared for this reason; e-macros declares 
the provided ones.) 


At the end of compilation, the compiler prints out the names 
of functions referenced in the code but not defined in the file, 
This is normal; however, you should inspect the list it prints 
out to see if any are ones that you thought you defined; if so, 
you have a problem. Check also for ones that are obvious typing 
errors. 
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While editing a large extension program, you may wish to 
load only the function that you are looking at on the screen into 
the editor environment. The function compile-function, on ESC 4C 
in Lisp mode, compiles the function you are looking at (whose 
Start is found by ESC “A from where you are now) into a temporary 
Segment in the process directory. It then loads the object 
segment, and displays the compiler diagnostics via local 
printout. It should be used with the cautions noted below. When 
using it, remember to write out your changes, and recompile your 
whole program, because a program incrementally debugged in this 
mode gives the impression that it is working properly when it is 
only doing so in the current editor environment. 


Compiling functions via ESC “C is often advantageous; the 
compiler produces diagnostics that help locate errors that you 
might not have encountered until your function ran, or perhaps 
not even then. ESC “C effects compilation and loading of the 
current Lisp function into your Emacs environment by loading the 
Lisp programs that constitute the Multics Lisp Compiler into your 
Emacs environment and invoking them. The loading happens only 
the first time Lisp mode ESC “C is used in an invocation of 
Emacs, and Emacs tells you when it is doing this. Emacs also 
loads the correct version of the e-macros include file during 
this first invocation. | : 


Forms compiled by Lisp mode ESC “C are treated as though 
they had been encountered by themselves in a source file being 
processed by the Lisp compiler. As viewed by the Emacs user, 
Successive compilations of functions via ESC ‘“C appear to be 
succesSive invocations of the Lisp compiler. This, however, is 
not an accurate description of what is taking place. As viewed 
by the Lisp compiler, which is then "living" in the Emacs 
environment, it is compiling one large source program consisting 
of many functions (i.e., Successive uses of ESC “C); all editing 
activity "between ESC “Cs" is irrelevant to it. Thus, invoking 
ESC “C for a Lisp macro definition defines that macro for all 
functions compiled by ESC “C in that invocation of Emacs from 
that point on. Therefore, you must ESC “C Lisp macro definitions 
if you intend to compile or evaluate function definitions using 
these macros. (In the case of macro definitions, ESC ‘“C 
(compilation) is equivalent to to ESC “Z (evaluation). Macro 
Gefinitions, whether ESC “Ced or ESC AZed, are accessible to 
functions ESC “Zed or ESC “Ced.) | 
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Similarly, Lisp "reader macro" character definitions must be 
evaluated if they are to be utilized by ESC “C. Declarations of 
Special variables (other than those declared for you in 
e-macros.incl.lisp) should also be ESC “Ced (not ESC “Zed) if 
they are to be respected by functions being ESC “Ced. Often, if 
you fail to do this, the compiler (ESC 4C) automatically detects 
undeclared use of special variables and warns you; however, in 
certain cases (most notably binding them via let), it does not, 
and erroneous code results. 


The compiler accumulates compilation Giagnostics in the 
buffer named “Compiler Diagnostics.” Diagnostics for each 
application of ESC “C are displayed as local display. 


DOCUMENTING REQUESTS 


The automatic documentation system (apropos, ESC 7?) 
provides customized Emacs request documentation. Documentation 
for supplied requests is kept ina special file in the Emacs 
environment directory. You can provide documentation for your 
own requests by placing a string, which is that documentation, as 
the "documentation" property of the symbol that is the request 
being documented. For instance, if the symbol 
remove-every-other-word has the documentation property of: 


"Removes every other word from the sentence in which the 
cursor appears." 


this information is displayed by ESC ? when used on some key set 
to remove-every-other-word, or by: 


ESC X describe remove-every-other-word CR 

Documentation properties are assigned most conveniently via 
the Lisp-special form “defprop", whose general syntax is: 

(defprop SYMBOL WHAT PROPERTY) 
This assigns the symbol (SYMBOL) a property (PROPERTY) of WHAT. 
The defprop is a special form because the actual symbols 
appearing in the form are used; they are not variables, as in "(+ 


a boc)". “Thus, 


(defprop Joe Fred father) 
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gives the symbol "Joe" a "father" property of "Fred". (The 
"defprop" is a special-form way of doing the same thing as the 
"putprop" function, but it is a special form because its 
"arguments" are not forms to be evaluated to produce symbols 
whose properties are to be dealt with, but the symbols 
themselves). To use defprop to establish Emacs request 
documentation, place forms like: 


(defprop remove- every other-word 
"Removes every other word from the current sentence. Will 
not work on sentences ending in ""?"", For indented 
sentences, use s$Sremove-other-word-from-indented-sentencess. 
$$$ is a powerful, dangerous, command.” 

documentation) 


Note several things about the documentation string: 


1. It does not need to end in a newline, and can contain 
newlines. 


2. Quotes (") inside of it must be doubled. 


3 The string "$ss" will be replaced by the key being 
asked about (6.9055 "ESC AZ or "ESC x 
remove-every-other-word") at the time the documentation 
is displayed. 


4, The keys used to invoke other requests can be 
referenced by stating two dollar signs, the name of the 


request, and one dollar sign. Thus, 
SSgo-to-end-of-lines appears as AE in most 
environments; the point of this and the- previous 
paragraph is to make documentation expansion 


independent of a user's key-bindings. 


The entire documentation string is "filled" (ESC Q) after 
all command-name substitutions are made; thus, the placement of 
newlines in the documentation string is ignored. Two consecutive 
newlines, however, are preserved, and thus, lines can be set off 
for examples, etc., by surrounding them with blank lines. 


It is slightly more efficient, but clearly less readable, to 
place the defprop documenting a request before the defun defining 
the request itself. The defcom facility can also be used to 
document requests; see "Defining Requests With defcom” below. 
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WINDOW MANAGEMENT 


Although buffers appear in windows on request, and are 
Switched between automatically by the redisplay when you switch 
windows with “X*4O, ‘X4, etc., there are times when you may want 
to take advantage of multiple windows explicitly. Good examples 
in supplied code are RMAIL reply mode and the comout-command 
(AXE). 


Mast of the extensions of interest are ones in which the 
extension writer wants to place some information in a buffer, or 
else prepare some buffer to have information placed in it (e.g., 
RMAIL reply) and then display that information in a window. 
Usually, all that is required is to "go to" that buffer (e.g., 
with go-to-buffer or go-to-or-create-buffer). The redisplay 
"finds". the editor in that buffer at the time of the next 
redisplay, and replaces the contents of the selected window on 
the screen. Such requests are called autophanic (self-showing). 
Examples are “XB (select-buffer) and “X4F (find-file). 


: ™~ 

However, some requests set up buffers in some window other 
than the current window, usually for multi-window operations such 
as mail reply, so as not to disturb the contents of the current 
window. They are called heterophanic (other-showing). The 
Standard examples are dired-examine, mail reply, and 
comout-command (XE). All the examples given are sub-requests 
of larger, autophanic requests. 


Heterophanic buffer behavior is provided by the function 
find-buffer-in-window. It takes as an argument a buffer-symbol 
(Lisp symbol representing a buffer). That buffer is created if 
it does not now exist, and is gone to, as if go-to-buffer had 
been used. If Emacs is in single-window mode, the effect is the 
Same as that of go-to-or-create-buffer. In two-window mode, that 
buffer is put on display as follows: 


2 If it is already on display in some window, it is left 
there. 
2 If it is not, it is put on display in some other 


window, one in which the cursor is not, and the cursor 
moves to that window, as if a “X40 had been done. The 
least-recently used window is chosen. 
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Thus, on printing terminals and in single-window mode, the 
effect of find-buffer-in-window is indistinguishable from that of 
go-to-or-create-buffer. In multi-window mode, it is equivalent 
to go-to-or-create-buffer, displaying that buffer in another 
window. 


You must not use find-buffer-in-window to place a buffer on 
the screen once you have already gone to it; if you think of 
find-buffer-in-window as a kind of go-to-or-create-buffer, you 
will find no need for doing so. 


3 An extension must establish multiple windows if it needs 
them; no current Emacs code requires multiple windows, aithough 
the facilities mentioned above are more useful when already in 
Loe: 


Most extensions that place an auxiliary buffer on display 
via find-buffer-in-window provide some request to return to the 
"main" buffer (e.g., the RMAIL Incoming Message buffer, the 
buffer from which “X‘E was issued, etc.). If you enter a buffer 
via find-buffer-in-window, you should probably return to the 
buffer from whence you came via find-buffer-in-window as well; 
the effect of this is to restore not only the original buffer, 
but also the original window. Thus, save-excursion-buffer cannot 
be used effectively to return from buffers entered via 
find-buffer-in-window; an attempt to use save-excursion-buffer 
results in both windows' showing the same buffer, since the 
Selected window (i.e., the cursor-bearing window) is changed and 
a new buffer selection means a new buffer in that window. 


The “X4Q key sequence should be used to exit auxiliary 
buffers used by extensions to return to their main buffer, and 
usually switch windows as well, if the multiple-window strategy 
outlined above is used. : 


Pop-up window mode, in essence, makes all requests 
heterophanic. Requests or subrequests that are naturally 
heterophanic need not worry about pop-up window mode, because 
find-buffer-in-window takes the appropriate action in either 
pop-up or non-pop-up mode. However, if proper heterophanic 
behavior under pop-up windows is desired, naturally autophanic 
requests and subrequests must call a window-management primitive 
to obtain heterophanic behavior in pop-up window mode. This 
primitive is called select-buffer-window. igs takes two 
arguments, a buffer-symbol, and a "key" that gives pop-up window 
management a preferred window size. 
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In non-pop-up window mode, select-buffer-window is 
equivalent to go-to-or-create-buffer, and the key is ignored. In 
pop-up mode, it is equivalent to find-buffer-in-window, with the 
key suggesting the new window size. 


The following values for the key argument to: 
select-butfer-window are accepted. They specify the window size 
in pop-up mode if the window does not exist already: 


any number 
‘ That many lines. 


"cursize 
Make a choice based on the current number of lines in 
the buffer. 
nil | 
Chooses some reasonable fraction of the screen. 
"cursize-not-empty 
Same as nil if the buffer is empty; same as 'cursize if 


it is not. For example, ‘“X4F uses this, because you 
can type into a new buffer. 


"default-cursize 
If this buffer has never been displayed before, makes a 
choice based on the number of lines. Otherwise, uses 
the Same size was chosen last time. 


The find-buffer-in-window can not be used to display the 
"current buffer” heterophanically. If you attempt to do this: 
(find-buffer-in-window current-buffer) 
you find it appearing in both the old and new windows, for the 


window manager finds that you were in this buffer in the current 
window (a truth) before you went to another one (you had to go to 


another one, as per heterophanic behavior), and indicates that " 


the current buffer is to be displayed in the old window as well, 
for that was the last buffer you were in in that window. To 
avoid this, use select-buffer-find-window (of two arguments, the 
buffer anda key as for select-buffer-window) if heterophanic 
display of the current buffer is needed: 


(select-buffer-find-window current-buffer nil) 


re, Since you seldom go to a buffer a 
=in inaneow it; in Emacs, only “X*E does 
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Since all things using these features are moderately 
sophisticated, only an outline of an extension using them is 
given here. It is a typical sub-subsystem (e.g., dired) that 
sets itself up in an autophanic buffer display, with specific key 
bindings, etc., and has a heterophanic subdisplay by which it 
displays a "menu" in addition to the main display: 


(defun unusual-mode () ;Setup function for this mode 
(go-to-or-create-buffer (maknam 
(explodec "Unusual buffer"™))) 
(set-key 'ESC-4S 'unusual-mode-show-menu) 
(select-buffer-window current-buffer nil) 
(register-local-var 'unuSual-mode-buffer-to-return-to) 


ec ccccccece) 


(declare (special unusual-mode-buffer-to- return-to) ); for compiler 
(defun unusual-mode-show menu () 
(setq unusual-mode-buffer-to-return-to current-buffer) 
;save buffer 
(find-buffer-in-window 'Unusual-Menu) ;Display menu 
(set-key 'r 'unusual-mode-select-item) ;Set key bindings 
(set-key '4X‘Q 'unusual-mode-menu-return) 
(insert-string "Unusual menu delicacies") ;Fill it up 
:; Will not actually be displayed until request finishes. 
(go-to-beginning-of-buf fer). 
(setq current-buffer-mode ‘'Unusual/ Menu 
buffer-modified-flag nil read-only-flag t) 


(defun unusual-mode-menu-return () 
Ceces buffer-in-window upusuaienede=bustecs to-return-to) ) 
;Return to calling buffer. 


The following are several primitives available to deal with 
windows by window number. The topmost window on the screen is 
window number i; the next one down, if any, is number 2, etc., 
(the minibuffer and mode line do not count as windows). The 
selected window is the one in which the cursor currently appears. 


selected-window 
This variable contains the number of the currently 
selected window. Do not attempt to setg it to select a 
window; use select-window instead. 


nuwindows 
This variable contains the number of windows on the 
screen; do not attempt to setq it to create or delete 
windows; use Gelete-window and the AX2 and 4X3 
functions to do these things. 


S=59 CJ52-01 


select-window 
This function (of one argument, a window number) 
selects that window (as *X4 with an argument does). 


delete-window. 

: This function (of one argument, a window number) 
removes that window from the screen, distributing its 
Space to the other windows. 


buffer-oan-display-in-window. 

This predicate function (of one argument, a 
buffer-symbol) returns truth if the specified buffer is 
on display in some window on the screen. If used as a 
function, i.e., the value returned is inspected, the 
returned value the window number in which the specified 
buffer is on display (1f it is not on display, the 
symbol "nil", representing falsity, is returned). 


window-info 

This function (of one argument, a window number) 
returns information about that window. The information 
igs in the form of a piece of Lisp list structure, which 
can be interpreted by the Lisp list destructuring 
functions; assuming that “into” has the result of 
window-info, the following forms return the information 
as. Eollows: 


(caar info) => The top line-number on the screen of 
the window. The topmost is 0. 
(cdar info) => The number of lines in the window. 


(caddr info) => The buffer-symbol of the buffer on 
display in the window. 
{cadddr info) => A string duplicating the contents of 
the “cursor line" of the window, 
including its newline character. The 
cursor line of a buffer is that line 
where the cursor is (if it is in the 
selected window) or would be if that 
window became selected (e.g., with 
4X0). 


window-adjust-upper 
A function of two arguments, the first a window number, 
and the second a signed number of lines to move its 
upper divider-line down (negative is up). 


window-adjust-lower 


Same .as window-adjust-upper, but deals with lower 
divider line. 
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WRITING SEARCHES 


Several functions aid in providing search-type requests. 
These functions prompt for the search string, provide default 
search strings, and announce search failure in a standardized 
way. All supplied Emacs searches use them. 


get-search-string ; 

Takes one argument, the prompt. The prompt should 
contain the word "search". The get-search-string 
prompts the user for a search string, which the user 
must terminate with a CR, and returns it as a string. 
If the user gives a null string, the last search string 
is used and echoed. The last search string is set to 
the returned string for the next defaulting. 


search-failure-annunciator : 
Causes the "Search Fails.” message to appear in the 
minibuffer, and a command-quit (“G) to be performed. 
' This aborts any keyboard macro collection or execution 
in progress. | 


When writing a search-type request, you should provide two 
interfaces, a "command", which calls the above two primitives, 
and a "search primitive", also called by the "command". The 
search primitive should return t (truth) if the search succeeds, 
leaving point at the proper place, as the search defines. If the 
search fails, the primitive must return nil (falsity), and leave 
point where it was when the primitive was invoked. 


'A Simple implementation of a wraparound search, below, first 
looks from point to the end of the buffer for the search string. 
If that fails, it goes to the top and searches again. It is not 
optimal because it needlessly scans farther than the original 
point when starting from the top. Using point>markp and 
searching a line at a time would be very expensive, due to 
point>markp's expense. Searching a line at a time using 
forward-search-in-line and mark-on-current-line-p would be 
acceptable, but more complex than this example need be. For a 
search that is probably going to be used only as a user interface 
Ci<@.5. Net internally), this implementation is adequately 
efficient. Recall that with-mark releases its mark and returns 
it last value. . 
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Here is the internal primitive for wraparound search: 


(defun wraparound-search-primitive (strinq) 


(with-mark m yRemember starting point 
(1£ (forward-search string);Look to end of buffer 
t ;Return truth 
else 
(go-to- bawtaneuaeste buffer} 
(i£ (forward-search string) sLook from top 
t. 
else 
(qo-to-mark m} ;Return ta orig. place 
mil)}}})} rReturn falsity 
se with-mark and this function 
ss return the value of the outer "if" 


The request for calling the primitive: 


(defun wraparound-search () 
(if (not (wraparound-search-primitive 
(get-search-string "Wraparound Search: *))) 
(search-failure-annunciator))) 


The wraparound-search request should have some key bound to 
it if this type of search is to be made available from the 
keyboard. 


CALLING MULTICS COMMANDS 


In some extensions, especially those like DIRED that 
manipulate the Multics environment, you must call Multics 
commands, or execute Multics command lines. 


Multics command lines are strings submitted to cu_Scep for 
execution. This is the Multics agency to which the "e" requests 
of the Multics edm and gqedx editors, the ".." requests of 
read mail, send_mail, and debug, and other subsystems submit 
command lines. The two primitives for executing Multics command 
lines are: 


e cline 

~ Takes one argument, a string, which is passed to cu_$cp 
for execution. No reattachment of output takes place. 
If the command line produces output, it messes Up the 
screen. This should only be used when no output is 
anticipated, and should be used then in or rated rence to 


awh we we we 


comout-get- output, since it is much faster. 
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comout-get-output 
Takes any number of arguments, which may be strings or 
Symbols, and catenates them with one space between them 
to form a Multics command line, facilitating things 
like: 


(comout-get-output ‘delete this-seg '-bf) 


Reattaches user_output and error_output during the 
execution, rerouting them to a process directory file. 
When the command execution completes, the contents of 
the current buffer are obliterated (!) and the 
temporary file read into it. This is the primitive 
that comout-command (*X*E) uses; e_cline_ is used by 
comout-get-output internally. 


These primitives set up a condition handler that catches all 
abnormal Multics signals and aborts to a second Multics command 
level with a message if one occurs. However, requests for input 
by these command lines cannot at this time be dealt with well. 
In the case of e_cline_, the user gets the query in raw teletype 
modes, and has to answer it in raw, nonedited teletype modes. In 
the case of comout-get-output, the query never appears, having 
been routed to the temporary segment, and the user's process 
hangs since the user, having never seen the query, does not know 
to respond. 


MULTICS ERROR TABLE 


To get the value of standard Multics error codes, from 
error _table_, into a program to see if a given Multics interface 
has in fact returned it, the function "“error_table_" (with 
underscores, not hyphens) is used. Its single argument isa 
symbol, whose name is the name of the error_table_ entry whose 
value is sought, and the returned result is that value, or 1 if 
it 1s not a valid entry. 


The error_table_ function optimizes finding the same name 
over and over again, so you need not go through machinations to 
Save an error_table_ value computed by these means. An example 
of the use of error_table_ follows: 


(let ((status-result (hces_sget_user_effmode dir entry ""))) 
(if (not (= (cadr status-result) 0) ;the return code 
(if (= (cadr status-result) 
(error_table_ 'incorrect_access) ) 
(display-error-noabort "Warning: not checking 


access") 

else 

(display-com-error (cadr status-result) dir ">" 
entry) ))) 
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EMACS ERROR SYSTEM 


Emacs has its own error system, with several functions 
available. They provide more error information than do the 
display-error and display-error-noabort functions (which simply 
take a string argument), because they are tied into the Emacs 
Brror Table. — 


report-error 
aborts the current computation and prints an error. 
report-error-noabort 
prints an error without aborting. 
add-error-code 
adds an entry to the Emacs Error Table 
error-table 
gets a standard Multics error code and returns the 


numeric value. 
Their syntax is: 
(report-error error-code error-information) 
(report-error-noabort error-code error-information) 
(add-error-code error-code error-string} 


(error-table segment offset) 


where: 


error-code 
is a symbol representing an entry in the Emacs Error 
Table (e.g., 'beginning-of-buffer), or is a standard 
Multics error code, or is a symbolic Multics error 
code, @.g., error_table_ Smoderr. 


error-information 
is any number of objects to print in the error report. 


error-string 
is a string describing the error. 


segment 
is a Multics error table segment. 

offset 
is the symbolic name of an error table entry, e¢.g., 
"moderr”™ in error table Smoderr 
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Defining Requests With defcom 


The defcom (for define-command) facility simplifies the 
definition of Lisp functions to be used as Emacs requests. 
Defcom cooperates with the Emacs command reader to provide 
prompting and defaulting of unspecified arguments, range-checking 
of numeric arguments, automatic repetition for numeric arguments, 
cross-connecting symmetrical functions via negative arguments, 
and other features. 


Defcom is a relatively new facility in the Emacs extension 
environment; not all of Emacs' internal code has been converted 
to use it. Perusing the Emacs source, you will find examples of 
defcom's use intermixed with older examples usang defun to define 
request functions. 


Defcom should only be used for defining functions actually 
to be used as Emacs requests; internal and auxiliary functions to 
.be used. by these functions should still be defined with defun. 
Emacs requests defined with defun will work, but those defined 
with defcom produce better diagnostics and offer more features. 
Defcom is a technique whereby the necessary defuns are generated 
automatically, so functions defined with defcom can be called 
from other functions, as well. 


To define a function with defcom, use defcom instead of 
Gefun, and supply no Lisp argument list: 


(defcom one-word-from-beginning 
(go-to-beginning-of-buffer) 
(forward-word) ) 


This is the simplest form of defcom; optional features are 
supplied by placing, between the function name and the function 
code, various keywords, all of which begin with the "&" 
character, and some of which take optional arguments, expressed 
as lists. | 


The most common optional specification is &numeric-argument, 
(or &na), which specifies what to do with a supplied numeric 
argument. The keyword é&numeric-argument must be followed by a 
list of specifications, which must include one of the following 
major processing types: 


&reject 
Any numeric argument is rejected as invalid. No other 
Specifications are valid in this case. This is the 
default if &numeric~argument is not given. 
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&ignore ~ | 
A nmumeric argument is ignored. 


&repeat 
If the argument is positive, the request is repeated 
that many times. 


&pass _ . . 
The value of the Lisp variable "numarg" is set, as in 
nondefcom requests: 


In addition to the major procéssing type, optional bounds 
cam be specified by the keywords &upper-bound (&ub) or 
&lower-bound. (&1b). These, in turn, must be followed by either 
an integer representing the bound, or the keyword &eval followed 
by an expression to evaluate at the time command execution is 
attempted, which then produces a value (such an expression is 
called an "&eval expression".) Here are some examples of 
&numeric-argument specifications: 

&numeric-argument (&pass) 
gument 
&repeat &lower-bound 1 . 

&upper-bound &eval (+ max-foos 2)) 


&numeric-argument 
(&pass &upper-bound 15.) 


Another optional function which specifies what ‘to do with a 
supplied mumeric argument is &numeric-function. The 
&numerie-function function doesn't actually do anything with the 
Supplied argument. Instead, it causes a different request to be 
executed if the original request is given a numeric argument. 


Here is am example of a &numeric-function function 
definition: 
(defcom global-print 


&numeric-function global-regexp-print 
eee }: 


It can be invoked as; 


case the global-regexp-print request is executed instead 
of the global-print request. 
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A request defined with defcom may elect to receive Lisp 
arguments, values that are to be prompted for or supplied as 
extended request arguments. They can be provided automatically, 
and prompted for, by the Emacs command reader, and supplied as 
Lisp arguments to the request function. Instead of a normal Lisp 
argument list, the keyword G&arguments (or &args or &a) are 
followed by a list of argument specifications, one for each Lisp 
argument to be supplied. 


Each argument specification consists of the Lisp name of the 
argument, i.e., the name of the variable to be referred to inside 
the function, and any number of argument qualifiers, separated by 
Spaces. Each argument qualifier can consist of several tokens, 
as necessary. Argument qualifiers specify the prompts, defaults, 
etc., for an argument. An argument specification may also be 
given as the name of the variable alone, as opposed to a list of 
it and qualifiers. In this case, it is equivalent to having its 
own name aS a prompt for its value. 


When a defcom-defined request is invoked as an extended 
request, (i.e., via ESC X), the Emacs command reader checks the 
type and number of request arguments supplied and necessary, and 
prompts for those not supplied, or defaults them as specified. 


When a defcom-defined request that has arguments is invoked from 
a key, it is as if it were invoked as an extended request with no 
request arguments given, and all are either prompted for or 
defaulted. | | 


The valid argument qualifiers are: 


&string 

&symbol 

&integer 
Specifies how the argument, when read by ESC X or 
prompted for, is to be converted before being passed. 
Only one of these is valid in a given argument 
specification, and &string (i.e., no conversion) is the 
default. 


&default 
Must be followed by either a string, symbol, or 
integer, aS consistent with the expected data type for 
this argument, or an &eval expression. Specifies the 
default value to be used if this argument is not 
Supplied, or a null response is given to a prompt for 
this argument, if any. 
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&prompt | 
Specifies the prompt for this argument, if not supplied 
via ESC X. Prompts are put to the user before defaults 
are evaluated or used; a null string causes the 
&default value to be used. An &prompt is followed by a 
prompt string (in quotes), or an &eval expression, and 
one of the two optional keywords NL or ESC, specifiying 
the prompt terminator (NL is the default). 


&rest-as-list 

Valid only for the last argument. Causes this variable 
ta be given, as a value, a list of all of the remaining 
supplied arguments. If &rest-as-list is used, the 
caller of this function from Lisp (including start-ups 
written by not- Lisp-conscious users) must know that the 
number and organization of Lisp arguments is different 
from the apparent argument array given to ESC X. 


&rest-as-string 
Valid only for the last argument; causes all remaining 
arguments to be supplied as a single string to the 
function, as they appeared to ESC X, with spaces and so 
forth included. Same cautions as for &rest-as-list 
apply. 


Sergi = 


A function definition that accepts three arguments follows: 


(defcom replace-n-times 
&arguments 
((oldstring &string &default &eval | 
(get-search-string "Old: ")) 
(newstring &string &prompt "New String: "™ NL) 
(count &integer &prompt "How many times? " NL 
&default 1)) 


(do-times count 
(if (not (forward-search oldstring) ) 
(search-failure-annunciator) ) 
(do-times (stringlength oldstring) (rubout-char) ) 
(insert-string newstring))) 
It can be invoked as: 
ESC X replace-n-times Washington Lincoln 2 CR 
Or 
ESC X replace-n-times CR 
in which case all arguments are prompted for, or: 


set-perm-key “29 replace-n-times 
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followed by striking *Z9 at some time, prompts for all arguments, 
too. This function is defined so that it can be called from Lisp 
as: 


(replace-n-times "this" "that" 17) 


or whatever, i.e., it is a Lisp function of three arguments. 


When defcom-defined requests are reexecuted by “C, they are 
repeated with $identical arguments. This is what makes 
search-repetition by “C work. 


In addition to numeric arguments and request arguments, 
defcom can be used Eo specify prologues, epilogues, 
documentation, cleanup functions, and negative functions of 
request functions. 


Prologues are functions or code to be executed before any 
arguments are prompted for, perhaps to check for valid 
Circumstances for calling this request. Prologues are only 
executed once. If the request is repeated because of a numeric 
argument, prologues are not repeated with each iteration. 
Prologues are specified by the keyword &prologue, and the name of 
a prologue function or an &eval expression. 


Epiloques are functions or code to be executed after each 
invocation of the request. If the request is repeated because of 
a numeric argument, epilogues are repeated after each iteration. 
Epilogues are specified by the keyword &epilogue, and the name of 
an epilogue function or an &eval expression. The epilogue 
function takes three arguments and is called as follows: 


(function prologue-info result lastp) 
where: 
prologue-info 
is the value returned by the prologue function, or nil if 
there isn't one. 
result ; 
is the value returned by the request itself on this 
iteration. 


lastp ; 
is non-nil if this is the last (or only) iteration. 
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Documentation is specified by the keyword &documentation (or 
&doc) followed by a documentation string subject to the same 
rules as given above under "Documenting Requests”. 


Cleanup functions are functions or code to be executed if 
the request is aborted. Cleanup functions are specified by the 
keyword &cleanup, and the name of a cleanup function or an &eval 
expression. The cleanup function takes one argument and is 
called as follows: 


(function prologque-info) 
where: 


prologue-info | 
is the value returned by the prologue function, or nil 
if there isn't one. 


Negative functions are functions or code to be executed if 
the request is given a negative numeric argument: the negative 
Function is given the negative numeric argument made positive. 
Negative functions are specified bY the keyword 
&negative-function (&nf£), followed by the name of the appropriate 
function, or forms, terminated by &end-code. The following is an 
example of the use of some of these features: 


(defcom forward-topic 
&doc "Goes forward one or more topics. See also 
| Ssbackward-topics.” 
&numeric-argument (&repeat) 
&negative-Eunction backward-topic 
(with-mark m 
(£orward—Ssearch "Topics. sida secseveus 


Emacs determines whether a character should stop echo 
negotiation by checking a list named "nobreak-functions". The 
defcom keyword &no-break adds the command being defined to the 
list. Keys bound to symbols on the list are echoed by the FNP, 
and do not interrupt the process (unless at end of line). 


Another defcom keyword, &completions (or &completion, &comp) 


provides minibuffer prompt completions. it allows any 
defcom-defined command to define completions that should be in 
effect for a given argument. The ESC SPACE request, 


complete-command, uses these completions to complete minibuffer 
input. An example of the &completions keyword is below: 
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(defcom new-function 
&arguments ((argl &prompt "What is arg one? " 
&completions '("one”™ "two")) 
(buf &prompt "OK, and in what buffer? " 
&completions known-buflist)) 
(minibuffer-print "Buffer is " buf ", argi " argi ".")) 


The argument after the &completions keyword is evaluated at the 
runtime of the function. The current list of completions is kept 
in the lisp variable completion-list. 


UNDOING A REQUEST 


The undo-prefix command, “\, sets the variable "undo” tot, 
which causes the next function called to attempt to do the 
reverse of its uSual action. Defcom-defined requests make use of 
this through the &undo-function (&undo, G&inverse) keyword. Its 
syntax can take one of six forms: 


&undo (&pass) [or the equivalent &undo &pass] 
&undo (&ignore) [or the equivalent &undo é&ignore] 
&undo (&reject) [or the equivalent &undo &reject] 
&undo function-to-call 

&undo (lisp expression to call) 

&undo &code lisp expressions &end-code 


If the defined request is prefixed by “\ when called, then the 
Special action is taken. Thus, if any of the last three forms is 
used, the function specified after the keyword is called instead 
of the defcom-defined request; if the first form is used, the 
variable "undo" is set to t and no special action is taken. This 
would mean, for example that "&undo &pass,” used in the 
definition of re-execute-command (“C), causes the sequence “*\%C 
to attempt to undo the last request executed. The second form 
causes the undo prefix to be ignored. The third form causes the 
default action, rejecting any undo prefix given. 
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A DETAILED EXAMPLE OF A FUNCTION DEFINITION 


The following example of a function definition for the 
String-search command uses many of the keywords described in this 
section: | 


(defcom string-search 
&inverse reverse-string-search 
&arguments ((Search-string &string &default 
&eval (get-search-string 
(search:numeric-prompt 
&prologue search:command-prologue 
&numeric-argument &repeat 
&negative-function reverse-string-search 
&epilogue search:command-epilogue 
&cleanup search: command-cleanup 
(forward-search search-string) ) 


The &inverse keyword indicates that A\AS calls the 
reverse-string-search command. 


The &arguments keyword indicates that “*S takes an argument 
named "Search-string” (the string to search for), which defaults 
to calling the get-search-string function in order to get the 
String from the user by a prompt. 


The &prologue keyword indicates that the prologue function 
named "search:command-prologue" runs before the first call of the 
forward-search command. In this example, the prologue function 
returns a cons of the number 0 and a mark set at the place from 
which the search began. 


The &numeric-argument keyword indicates that ESC N “S calls 
the forward-search command N times. 


The &negative-function keyword indicates that ESC -N “§S 
calls the reverse-string-search command, with a numeric argument 
of N. 
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The &epilogue keyword indicates that the epilogue function 
named "“search:command-epilogue" runs after each call of the 
forward-search command. In this example, the epilogue function 
Goes various bookkeeping operations for the forward-search 
command, deciding whether the command should continue or not. 
When the search fails, it aborts the command. The epilogue 
function is called with three arguments, which are as follows: 


prologue-info: 
in this example, whatever the &prologue function 
returns, which is a cons of a number anda mark; used 
by the epilogue function to store the iteration count. 


result: | 

in this example, whatever the forward-search function 
returns, which is non-nil if the search was successful; 
used by the epilogue function to decide whether to let 
the function continue or not. 


lastp: 
in this example, non-nil if this is the last iteration 
of the forward-search function; used by the epilogue 
function to decide whether to set a gratuitous mark if 
the search failed. 


The &cleanup keyword indicates that the cleanup function 


named "“search:command-cleanup” runs when the forward-search 
command is aborted. In this example, the cleanup function 
decides whether the forward-search command should go back to the 
beginning or not. The cleanup function is called with one 


argument, prologue-info, which is modified by the epilogue 


function as described above. 


The forward-search command is the actual code in this 
function definition of the string-search command. In this 
example, it's just one function call, but it could be several. 


You should note that most of the keywords are interpreted by 
the Emacs command loop. This means that they can be ignored when 
@ command is called directly as a function, as it is in extension 
code. The main exception to this is the &arguments keyword. 
This keyword sets up an argument list for the function, so the 
function requires that those arguments be given explicitly in the 
function cail. 


In the example above, this means that calling string-search 
is equivalent to calling forward-search, because all 
String-search does is call forward-search with its arguments. 
All of the other functions are executed before or after 
forward-search is executed, without its knowledge. 
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SECTION 4 


LDEBUG MODE 


Emacs LDEBUG mode (Lisp Debug) provides an interactive Lisp 
environment designed for the debugging of Emacs extension code. 
Facilities are provided for tracing the Lisp stack, breakpointing 
code, and interacting with the native MacLisp trace facility. 
LDEBUG mode is specifically optimized for multiple-window 
interaction. 


LDEBUG BUFFER 


The heart of the LDEBUG mode facilities is the LDEBUG 
buffer. The buffer mamed LDEBUG, when created by ldebug mode 
(either in response to a breakpoint's being executed, a trapped 
Lisp error, or the explicit "ldebug” extended request), evaluates 
any Lisp form typed into it when carriage return is struck after 
it. The form must be on one lines an error occurs if the form 
has syntactic errors (e.g., miscounted parentheses). The result 
of the evaluation is placed in the LDEBUG buffer on the next 
line, following the sign "=>", which indicates the result of such 
an evaluation. The Lisp variable "*" is set to the result of 
each succesSive evaluation, as at raw Lisp top level; this may be 
used to reference the last printed result. | 


Random Lisp forms such as "(+ 2 3)" or "“current-buffer" can 
be typed at LDEBUG buffers, and the resulting buffer contents 
will in effect be a dialogue of an interaction with Lisp. Such 
buffers are often dprintable for later perusal. The values of 
variables can be set by evaluating the normal Lisp setq forn, 
e.g., (setq var (+ foo 27)). As lines are placed into the LDEBUG 
buffer by the LDEBUG facility, the window (if any) containing it 
scrolls, if necessary. 
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Lisp values “printed” into the LDEBUG buffer are by default 
limited in length to ten and depth to six. The values of the 
option variables "ldebug-prinlength" and "ldebug-prinlevel” can 
be set to alter these defaults. The default input and output 
radices are both 8: these can be altered as the option variables 
"Ldebug-ibase” and "ldebug-base”. As with ESC ESC, "#" 
represents elements deeper than the depth limit and "..." 
elements longer than the length limit. 


Most. Emacs requests can be used in LDEBUG buffers; they are 
im Lisp Debug mode, which is an extension of ordinary Lisp mode, 
with requests differing as detailed below. 


The ldebug (ESC X ldebug CR) extended request can be invoked 
at any time, in the usual way Emacs extended requests are 
invoked. It places Emacs in the LDEBUG buffer as described 
above, and also sets up a system of Lisp error handlers "under" a 
new invocation of the Emacs request loop. Should any Lisp error 
occur while these handlers exist, the LDEBUG buffer is entered, 
Dlaced on display if not already on display, the terminal's bell 
is beeped, and the Lisp error message is entered in the LDEBUG 
buffer. You are then at a “second (or greater) level" of LDEBUG, 
Similar to being at Multics command level when an error occurs. 
The level number is part of the message entered in the LDEBUG 
buffer. 


Recursive (level greater than 1) LDEBUG buffers can be 
released (aborting all executing code between the LDEBUG level 
being released and the previous level) via the ESC G 
(ldebug-return-to-emacs-top-level) request, the analogue of the 
Multics release command. It beeps and types "$g" in the LDEBUG 
buffer. The value of the variable ldebug-level tells the current 
level of LDEBUG buffers. 


ESC P (for proceed) is the analogue of the Multics start 
command; more about its meaning for each different type of entry 
to an LDEBUG buffer is described below. In general, it restores 
the buffer and window from which the LDEBUG buffer entered. 
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When an error trap entry to the LDEBUG buffer has occured, 
the Lisp stack can be traced via the ESC T (ldebug-trace-stack) 
request, and the value of variables can be inspected simply by 
typing their names (Since they are Lisp forms) to the LDEBUG 
buffer. For this to work most effectively, at least one level of 
LDEBUG should be in the stack before the error is encountered. 


A value can be returned to the Lisp error handler by typing 
it on a line, and instead of ending the line with carriage return 
(which would evaluate and "print”™ the result), ending it with ESC 
P. Lisp error handlers often want a list of the value to replace 
some erroneous value. For instance, in the following dialogue, 
an LDEBUG trap was entered because of the unbound variable 
"stuff": the programmer returned the symbol "value-i-wanted” as 
the intended value of the unbound variable: 


(myfun huff stuff) 


Lisp breakpoint unbnd-vrbl at level 1 in buffer LDEBUG: 
lisp: undefined atomic symbol stuff 


('value-i-wanted)$p 


All correctable Lisp error breakpoints accept a retry value to be 
used to retry the failing operation; the undefined function 
breakpoint ("undf-fnctn") also accepts a list of a new value, in 
this case a function to be used instead. 


The "Sp" is always printed by ESC P, to remind the user of 
the $p which is used in raw Multics MacLisp to restart breaks. 
ESC P can also be used alone on a line (i.e., no value to be 
returned preceding it) to restart a break and let Lisp's default 
action occur. | 


ESC G can be used as usual to release a level of errors to 
the next lower LDEBUG level; “G (command-quit) does not release 
past LDEBUG levels. 
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CODE BREAKPOINTS 


Breakpoints can be set in interpreted extension code being 
debugged by typing ESC & in a Lisp Mode buffer with the cursor at 
the point in some function being debugged where you would like 
this break set. The LDEBUG mechanism creates this breakpoint by 
putting a call to a tracing function ("%%") in the code in the 
buffer, and evaluating the function definition it is looking at. 
This break code is left in the function to let you know that it 
is. there: it includes a break number (they are assigned 
sequentially) to which this breakpoint can be referred by 
requests yet to be described. 


You should be in at least one level of LDEBUG buffers before 
setting a break: thus, you should have said "ESC X ldebug CR" 
some time before setting breaks. 


Having set a break, you can run the code being debugged. 
When the breakpoint is entered, the LDEBUG buffer is entered at a 
new higher level. A message of the form: | 


Break 4 in function testfun 

is put in the buffer, and the LDEBUG buffer is put on display. 
As. in all LDEBUG buffers, arbitrary forms can be evaluated 
(including inspecting variables), and ESC T can be used to trace 
the Lisp stack. Again, ESC G releases a level of LDEBUG buffers. 


ESC P is used to restart code breakpoints as well. A given 
breakpoint can be set for some number of proceeds (i.e., "3" 
means proceed, and proceed this breakpoint the next two times it 
is encountered automatically) by giving that number as a numeric 
argument to ESC P (i.e., ESC 3 ESC P). A message indicating the 
number of proceeds is inserted in the LDEBUG buffer. ESC P 
should be used alone on a line (i.e., no retry value) when 
restarting code (or trace) breaks. 


When in a code break, ESC R (ldebug-reset-break) resets the 
current breakpoint, before restarting or releasing. The break 
code is removed from the function definition (visibly, if it is 
on display), and the function definition is reevaluated. ESC R 
with a numeric argument can be used to reset a break by number. 


In an LDEBUG buffer, ESC L (idebug-list-breaks) lists ail 
the known code breakpoints: their numbers, the function in which 
each break appears, the buffer that function appears in, and the 


Status of each break. 
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The source for the current breakpoint can be shown by 
issuing the request ESC S (ldebug-show-bkpt-source). It is 
placed in an available window (if in multiple window or 
pop-up-window mode), and the cursor is moved to the break code. 
Use “XO to get back, or, in one-window mode, “XB CR. 


During function breakpointing, to determine where the editor 
was (i.e., what was the current buffer, and where was the current 
point) at the time the breakpoint was encountered use ESC “S 
(ldebug-display-where-editor-was). It selects the appropriate 
buffer, moving the cursor to the point in it where the current 
point was when the breakpoint was taken. If the buffer is 
already on display in some window (or pop-up windows are being 
used), that window is selected, and “XO returns you to the LDEBUG 
buffer for further probing or restarting. In one-window mode, 
the correct buffer is switched to, and “XB gets you back. If the 
current point is moved by you explicitly (i.e., via normal Emacs 
requests) while visiting the buffer where the breakpoint was 
taken, it has its new position when the breakpoint is restarted. 
This is analogous to setting a variable before restarting with 
usual Multics debugging. | 


Using two or three windows to contain the LDEBUG buffer, the 
breakpoint source (function being debugged), and the buffer the 
functions being debugged are working on, is highly effective. 


FUNCTION TRACING WITH LDEBUG 


The standard MacLisp trace package can be used while in 
Emacs; extensibility features of the former allow LDEBUG to take 
control of the trace output and breakpointing provided by it. 


All the facilities of the standard trace package can be 
used, by invoking trace from ESC ESC minibuffers. The trace 
package allows tracing of entries and exits to functions, 
arguments, and return values, and breakpoints when functions are 
entered. Some sample forms to trace the function testfun are 
given here: these are in Lisp syntax, and can be typed as such 
to LDEBUG mode. When typed to an ESC ESC minibuffer, the outer 
set of parentheses should not be supplied. 

(trace testfun) 

Traces the input arguments and returns value of testfun 
each time it is invoked. 


(trace (testfun break (< x 3))) 
Traces input and returns value of testfun, enters a 
breakpoint when entered and x (x can be an argument to 
testfun) is less than 3. 
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(trace (testfun break t)) 
Same, but enters a breakpoint at every entry to 
testfun. 


(trace (testfun entry (a b) exit (c))) 
Traces input arguments and returns value. Also prints 
out the values of a and b when testfun is entered and 
the value of c when it is exited. 


The general syntax of trace invocations is (brackets 
indicate optional clauses, and angle brackets are syntactic 
variables): 


(trace <fnname-or-clause-1> ... <fnname-or-clause-n>) 


where <fnname-or-clause> is either a function name to be traced 
for input arguments only and return value, or: 


(<fnname> [break <break-condition>] [entry (<entry-vals>) } 
{exit (<exit-vals>)]) . 


When a function is traced within Emacs (it is not 
recommended to trace internal Lisp or Emacs primitives, and no 
part of the redisplay should be traced in this way), trace output 
for entry and exit tracings are placed (and scrolled) directly 
into the LDEBUG buffer if it is on display; if it is not on 
display, this output is put in the LDEBUG buffer, and locally 
displayed as it is produced. The line of dashes and asterisks of 
local displays is not produced, as it cannot be known when the 
end of trace output has been reached. Thus, traced functions 
invoked from the minibuffer may often leave the cursor in the 
minibuffer awaiting clearing of the local display via linefeed or 
a 


Trace output generally looks like: 
(3 enter testfun (3 5 (a . b)) /J/| (4 5)) 


The indentation level gives the depth in currently active traced 
functions. The "3" is the recursion depth of the given function 
(e.g., testfun) being traced. The "enter" is the type of trace 
(enter vs. exit), (3 5 (a . »b)) is the list of arguments (in 
this case, three arguments). The /|/| sets off the entry values 
and exit values optionally selectable by the entry and exit 
keywords in the trace-invoking form. Exit traces look like: 
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If trace is used to set an entry breakpoint, the LDEBUG 
buffer is trapped to at the time the traced function is entered, 
in a way very much like a Lisp error break to LDEBUG. A message 
such as; ; 


Entry breakpoint to function testfun 


is printed into the LDEBUG buffer, and the terminal beeped. As 
with LDEBUG code breaks, ESC G releases, ESC P restarts, ESC R 
resets, and ESC “S shows where the editor was at the time the 
break was taken. When in entry breakpoints to interpreted 
functions, the arguments can be inspected by name. ESC T can 
trace the Lisp stack, but unless *rset t mode was in effect 
(setting up an LDEBUG level does this automatically), trace 
information may not be present. 


It is not necessary to have invoked ldebug before invoking 
trace in Emacs; LDEBUG is invoked automatically if an attempt is 
made to uSe trace in Emacs. If some critical mechanism is being 
debugged and normal trace handling (i.e., breakpointing/tracing 
to user_i/o from Lisp, not the Emacs handling just described) is 
necessary, the variables trace-printer and trace-break-fun should 
be made unbound (e.g., ESC ESC makunbound 'trace-printer) before 
the first reference to trace in a given invocation of Emacs. 
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SECTION 5 


WRITING EMACS TERMINAL CONTROL MODULES (CTLS) 


Support of video (and printing) terminals in Emacs is 
accomplished via terminal-dependent modules known as CTLs. There 
are about two dozen supplied CTLs. Emacs attempts to locate an 
appropriate CTL by using the regular search rules, based upon the 
terminal type maintained by Multics, and optional Emacs control 
arguments. The list_emacs_ctls command is provided to list all 
the known terminal CTLS. | | 


To support a type of terminal not supported by a supplied 
CTL, you must write a new CTL. A CTL is written as a Lisp source 
program, named TTYTYPE.ctl.lisp, where TTYTYPE is the name of the 
terminal type to be supported. If this terminal type is in your 
Site's Terminal Type File (TTF), the name chosen should appear 
the same as it appears in the TTF, except that the name of the 
CTL should be all lowercase (Emacs lowercases terminal types when 
looking for CTLs). 


CTLS are usually written by example from supplied CTLs. 
Personnel with no knowledge of Lisp at all have achieved this 
successfully. Once the CTL is written, it must be compiled 
before it can be used. Compilation is performed via the Lisp 
compiler, lcp. A typical command line to compile a CTL is: ; 


lep super58.ctl 


This produces an object segment, super58.ctl. 
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Two control arguments for setting the terminal type are 
recognized by Emacs when given as a command line argument. These 
are: 


emacs -terminal_type STR or emacs -ttp STR 

where STR is your terminal type. The value of STR 
can be any recognized editor terminal type. The CTL 
is found via the user's search rules. The terminal 
type given by STR is set only for the current 
invocation of Emacs; in subsequent invocations, Emacs 
checks your Multics process terminal type if you have 
not respecified it with -ttp. 


emacs -query 
Emacs queries the user for the terminal type without 
checking the Multics terminal type first. The answer 
you give may be any STR accepted by the -ttp option. 


Added names and links can be used to support many TTF 
terminal types via one CTL. When Emacs is given a terminal type 
(either from Multics Communication System or the -ttp control 


a e e a iad s 
argument) for which it cannot find a CTL, it asks you if you want 


to see the list_emacs_ctls list of known terminal CTLs. 


The most effective method of writing a new CTL is to take 
one that was written for a similar terminal and modify it. 
Almost all of the extant CTLs were written in this way. The 
sources are Lisp source segments, generally one or two printed 
pages long. Good starting points are: 


2 vip7200.ctl.lisp, typical of terminals that do not have 
the ability to insert or delete lines or characters. 


a vip7800.ctl.lisp, typical of terminals that do have 
these abilities. The two facilities are independent, 
either one, both, or neither may be present, although 
use of terminals without insert/delete lines at less 
than 1200 baud may be found to be unacceptable. 


The interfaces (function definitions) in a CTL are 
Standardized. They have the same names in all CTLs. The Emacs 
Screen manager calls these interfaces anonymously after the 
appropriate CTL has been loaded. The interface DCTL-init is 
called at Emacs start-up time; it has the responsibility of 
setting various flags, and initializing the terminal. It should 
contain the statements: 7 


a=2 CJ52=01 


(setq idel-lines-availablep t) 
if the terminal can insert/delete lines. 


(setq idel-lines-availablep nil) 
if it cannot. — 


(setq idel-chars-availablep t) 
if the terminal can insert/delete/ characters. 


(setq idel-chars-availablep nil) 
if it cannot. 


(setq tty-no-cleolp t) 
if the terminal has no clear-to-end-of-line facility. 
Such terminals are generally unsatisfactory at speeds 
less than 2400 baud. 


(setq region-scrool-availablep t) 
if the terminal has region scrolling (see below). 


(setq screenheight N.) | 
where N is the number of lines on the screen (note 
the dot after the N). 


(setq screenlinelen M.) 
Where M is one less the number of characters ina 
line on this terminal. Again, note the dot. 


(setq tty-type 'TYPENAME) 


Where TYPENAME is a word like "“super58”" that 
identifies the terminal type. 


At the time DCTL-init is invoked, the variable ospeed is set 


to the speed of the communications line in characters per second 


(e.g., 1200 baud is 120 chars/sec). This can be used to perform 
padding calculations. This value is usually computed from the 
line speed maintained by the Multics Communication System. The 
-line speed control argument can be used to specify terminal 
speed for users logged in via the ARPANET. 


In addition, you can use the -page_length or -line_length 
control arguments to override the terminal controller defaults 
for page and line lengths. 
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Also before DETL-1nit is invoked, the variable 
given-tty-type is set to the name by which the CTL was loaded 
with the "ctl" suffix stripped. This variable can be used in 
DCTL-init (and elsewhere) to enable and use different features of 
a terminal dependent on the name used to reference that terminal. 
To ensure that given-tty-type is different for various versions 
of a terminal, give the additional varieties of the terminal as 
added names on the CTL segment. For example, the names 
vtloOw.ctl, vti00ws.ctl, and vti0O.ctl are all associated with 
the same CTL segment. This allows the VT100 CTL to distinguish 
between various screen widths and heights.by using the value of 
given-tty-type. The "eq" predicate (i.e., (eq given-tty-type 
'dd4000)) can be used to check the value of this variable. The 
variable tty-type should be set by the CTL to a generic terminal 
type, e.g., vti00 for all varieties of VT100, as opposed to the 
type given in given-tty-type. 


The following functions are available to the CTL writer: 
S Rtyo takes one argument, a number (fixnum), and outputs 


that mumber as ASCII data. For example, (Rtyo 141) 
outputs an "a", and (Rtyo 33) outputs an ESC, 


iB 


Rorinc takes one argument, a character string, and 
outputs it. For example, (Rprine "JI") outputs a right 
bracket and an I. 


Both of these functions buffer their output until the Emacs 
Screen manager dumps this buffer. This is always done at the end 
of any redisplay at all, and after DCTL-init is called. 


The CTL writer must maintain the values of the special 
(global) variables X and Y relative to a zero origin screen 
position where the cursor was left. In return, you get to 
inspect these variables to do positioning optimization. 


The CTL writer must provide the following interfaces to be 
called by the Emacs screen manager: 


2 DCTL-init (no arguments). Must set the flags listed 
above, initialize the terminal (1f necessary), clear 
the terminal screen, and leave the cursor at position 
(0, 0) (home). 
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& DCTL-position-cursor (two arguments, a new X position 
and a new Y position). Move the terminal's cursor to 
the given position. Position 0, 0 is defined as the 
upper left hand corner of the screen. This function 
must check the variables X and Y, and output no 
characters if the cursor is known to be already at the 
desired position. Otherwise, it must use the values of 
X and Y to determine what type of motion is necessary, 
output characters to move the cursor, and update X and 
Y to the input parameters (the delay of the buffered 
output is not an issue). 


Typically, DCTL-position-cursor determines which is the 
optimal movement based upon the relative positions of the cursor 
and the desired position. For terminals that have many forms of 
cursor movement, some combination of backspaces, linefeeds, and 
Carriage returns may be adequate to effect some forms of cursor 
movement. Sometimes the sequences generated by the arrow buttons 
on the terminal may be used for relative positioning. Just about 
all terminals include some form of absolute positioning. The 
choice of optimal cursor positioning should be based upon which 
will output the fewest characters to effect the desired move. 
See hp2645.ctl.lisp for an example of a very well optimized 
cursor positioner. 


One useful trick in the writing of DCTL-position-cursor is 
the use of recursion. See adds980.ctl.lisp for an example. If 
you choose to use terminal tabs, then your DCTL-init must set 
them, and you must take care not to clear them. No supplied CTLs 
(other than the extremely special-case printing terminal 
controller) use tabs. | 


8 DCTL-display-char-string (cne argument, a character 
String to be displayed). Must output this character 
String to the terminal at the current assumed cursor 
position. The string iS guaranteed to contain no 
control or other nonprinting characters, and each 
character in it is guaranteed to take up only one print 
position. Be careful to update cursor position after 
printing the string; the lisp function stringlength may 
be used to ascertain the length/printing length of the 
string. 
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2 DCTL-kill-line (no arguments). Clear the line from the 
current assumed cursor position to the end of the line, 
and leave the cursor at that original assumed position. 
Most video terminals have a clear-to-end-of-line 
feature; it should be used here if available. Some 
terminals do not, so the flag tty-no-cleolp must be set 
to indicate this and DCTL-kill-line not defined. If 
this flag is set, the Emacs redisplay simulates 
clear-to-end-of-line by overwriting portions of lines 
with spaces. This technique is tedious but necessary. 


a DCTL-clear-rest-of-screen (no arguments). Clear the 
screen from the current assumed cursor position to the 
end. Leave the cursor where it was supplied. Some 
terminals have a "clear whole screen” function, but not 
clear to end of screen. Currently, you can use the 
clear whole screen function. If your terminal does not 
even have a clear-whole-screen function, it is probably 
not. worth using with Emacs. If you choose to use tabs 
in cursor positioning, be wary of clearing them via 
this function. 


Those are all the required functions. Some terminals 
require control sequences to change modes between normal Muitics 
operation and operation within Emacs. (For example, a terminal 
might be Switched between line-at-a-time transmission and 
character-at-a-time transmission.) Yet other terminals might use 
features during. the operation of Emacs that should be 
disabled/reset when using Multics. (For example, the Digital 
Equipment Corporation VT100 uses "Scroll" regions to simulate 
insert/delete lines. However, if a scroll region exists, it 
makes parts of the screen unusable when using Multics.) It is 
possible and quite common to switch between Multics and Emacs by 
using the ATTN key and the program_interrupt command. In such 
cases, the terminal is in the wrong mode at various times. If 
the terminal for which you are writing a CTL exhibits this 
behavior, you should add the following statements to DCTL-init: 


(setq DCTL-prologue-availablep ¢t) 
to specify that certain functions must be performed 
each time Emacs is entered from Multics. 


(setq DCTL-epilogue-availablep t) 


to specify that certain functions must be performed 
each time Multics is entered from Emacs. 
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In addition, you must then supply the following two functions: 


If 


DCTL-prologue (no arguments). Perform any operations 
that are required when Emacs is entered from Muitics. 
This function is invoked immediately after DCTL-init is 
called and after Emacs is reentered after a QUIT via 
either the Multics program_interrupt or start commands. 


DCTL-epilogue (no arguments). Perform any operations 
that are required when Multics is to be entered from 
Emacs. This function is invoked immediately before 
Emacs is exited when the “*X‘C (quit-the-editor) request 
is invoked, and immediately before Emacs is suspended 
when the *Z42 (quit) request is invoked or the ATTN key 
is hit on the terminal. 


you have stated that insert/delete lines is available, 


via setting the flag idel-lines-availablep to t, you must supply 
the following two functions. If you set this flag to nil, you 
need not write these functions: 


DCTL-insert-lines (one argument, a number of lines to 
be inserted). Open up the given number of lines on the 
screen. There are that many blank lines (created by 
DCTL-delete-lines) at the bottom of the screen at the. 
time this function is invoked. The cursor is at 
position 0 of some line at the time DCTL-insert-lines 
is invoked. It must push the contents of that line 
down the supplied number of lines, leaving the cursor 
in the same place, and the line the cursor is on and 
the n-1 succeeding lines blank. 


1 


@ DCTL-delete-lines (one argument, a number of lines to be 


If 


that 


deleted). Delete from the screen the supplied number 
of lines, starting with the line the cursor is on and 
proceeding downward. The cursor 1s to be left in the 
Same place it was given. That many blank lines are 
assumed to be pulled up on the bottom of the screen. 


the flag idel-chars-availablep is set tot, indicating 
insertion and deletion of characters is available, the 


following two functions must be supplied: 


DCTL-insert-char-string (one argument, a character 
String to be inserted at the current assumed cursor 
position). Insert the character string supplied at the 
current cursor position. Push to the right all 
characters at, and to the right of, the current cursor 
position. There are only blanks on the screen in the 
region being pushed off. Leave the cursor (and so 
updat) after the last character of the inserted string. 
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2 DCTL-delete-chars (one argument, the number of 
characters to be deleted). Physically delete from the 
screen the supplied number of characters, starting with 
the character at the cursor and on the right. Move all 
characters to the right of these characters that many 
positions to the left. That many blanks are assumed to 
be moved in from the right edge. Leave the cursor 
where it was supplied. 


Some: terminals, such as the DEC VT100 and the Human Designed 
Systems Concept 100, offer a feature called region-scrolling, 
which allows groups of lines to be moved up or down at once 
without the two-step operation of delete-lines followed by 
insert-lines. The Emacs redisplay can take advantage of this 
feature; the result is scrolling without the "jumping 
minibuffers" and pulling and pushing associated with window 
Management via insert/delete lines. If your terminal has region 
scrolling, do not define DCTL-insert-lines and DCTL-delete-lines 
for your terminal. Instead, setq the special variable 
region-scroll-availablep to t at DCTL-init time. The following 
two functions must then be defined: 


@ (defun DCTL-scroll-unp-region (amount bottom)...) 


This operation will be invoked with the cursor at the beginning 
of some line of the screen. It defines an operation affecting a 
region that includes the current line down to, but not including, 
the line designated (by number, in the second argument) as the 
<bottom> (where the first line on the screen is 0). This region 
ls scrolled up by <amount>, where amount is the number of lines 
given as the first argument. The cursor is left where it is, at 
the beginning of the newly scrolled-up current line. So, in 
efect, where <size> is the size of the region (in lines), the 
lower <size minus amount> lines of the region are moved up to 
become the topmost <size minus amount> lines of the region. The 
last <amount> lines of the region are left blank, and the 
contents of what were the first <amount> lines depart 
irretrievably from the screen. In the following example, assume 
C represents the cursor and call: 


(DCTL-scroll-up-region 2 7) 


Before After 
Foo Foo 
Bar Bar 

CQuux CLuux 
Truux Buux 
Luux Bears 
Buux 
Bears 
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Cubes Cubes 
Emacs Emacs 


The second function is: 
@ (defun DCTL-scroll-down-region (amount size)...) 


This operation will be invoked with the cursor at the beginning 
of some line of the screen. It defines an operation affecting a 
region that includes the current line down to, but not including, 
line number <bottom>, where the first line on the screen is Q. 
The size of this region, in lines, is <size> (the second 
argument). This region is scrolled down by <amount> (the first 
argument) lines, and the cursor left where it is at the beginning 
of the current line of the screen. So, in effect, the upper 
<size minus amount> lines of the region are moved down to be the 
bottommost <size minus amount> lines of the region. The first 
<amount> lines are left blank, and the contents of what were the 
last <amount> lines departs irretrievably from the screen. 


Again, in the following example assume C represents the 
cursor and call: 


(DCTL-scroll-down-region 2 7). 


Before After 
Foo Foo 
Bar Bar 

CQuux Cc 
Truux 
Luux Quux 
Buux Truux 
Bears Luux 
Cubes Cubes 
Emacs Emacs 


Writing a CTL usually involves editing an existing one, 
trying it, modifying it, and iterating until it is solid. You 
use the -ttp control argument many times to switch back and forth 
between printing terminal mode and the new CTL when logged in 
from the terminal on which the CTL is being developed. For 
terminals with insert/delete features, it may be convenient to 
debug the CTL first without these features (claim they are not 
there in the DCTL-init), and add them later. Similarly, you are 
encouraged to write a better DCTL-position-cursor once you have 
one that works at all, for the convenience of editing the CTL 
with Emacs substantially reduces the effort of improving it. 
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For some terminals, padding may be necessary for some 
operations at some or all line speeds. If terminal behavior 
appears random, or garbage is left on the screen after a “L or 
AK, this may be the problem. Check the manual for your terminal 
about padding requirements. It may be convenient to define a 
function called DCTL-pad, which takes a number of microseconds or 
milliseconds as an argument, and issues enough pad characters to 
perform this padding. (Rtyo 0) or (Rtyo 177) are common, but 
check your terminal manual for what your terminal expects; (Rtyo 
0) generally works. The variable ospeed gives the line speed in 
characters per second, for use in such calculations. Getting the 
padding right may involve quite a bit of tinkering on some 
terminals; one proven method in cases where padding is felt to he 
a problem is to specify a very large amount of padding (e.g., a 
second) and cut it down until it works. See dd4000.ctl.lisp for 
an example of terminal padding. 


The Lisp special forms cond and do are used heavily in CTLs. 
Since Emacs environment macros (do-forever, if, etc) should not 
be used in CTLs, the native Lisp forms are necessary. Here are 
the descriptions of cond and do: | 


(cond ((= this that) (thingl)(thing2) ) 
((> a b)(second) (third) 27) 
((< ¢ 15) (other) ) 
(t. (best 5) (chance))) 


means: 


"If this equals that, call thingl of no arguments, then call 
thing2 of no arguments, and return as the value of the cond 
the value returned by thing2. Otherwise, if a is greater 
than b, call "second" with no arguments, then call "third", 
and return 27 as a value. Yet otherwise, if c is less than 
15 (all numbers octal), return the value obtained by 
applying "“other™ to no arguments. I£ none of the above are 
true, call "best" with an argument of 5, and then return the 
value obtained by calling "chance" with no arguments." 
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The cond special form is much like PL/I's 


Vf (igus s — then ido: 

end; e668 e 

else if ( .... ) then do; 
end: e#eoeses 

else if ( .... )} then do; 
end: *¢e@e@ee#8e 

else do; 


end; 


The format of Lisp "do" used in CTLs to iterate is: 


(do VARIABLE INITIAL-~VALUE REPEAT-VALUE TEST formi form2 
form3.. ) 


It is equivalent to PL/I's: 


do VARIABLE = INITIAL-VALUE 
repeat REPEAT-VALUE 
while (“ TEST); 


formi;form2; ... 
end; 


which, itself, is equivalent to: 


VARIABLE = INITIAL-VALUE; 
i if TEST then go to e; 

formi;form2; ... 

VARIABLE = REPEAT-VALUE; 
go to l; 
e: 7 


The variable VARIABLE is locally defined inside the do. It may 


be used in the forms inside the do, in the "end test” TEST, and 
in the repeat value REPEAT-VALUE. 
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APPENDIX A 


THE BACKQUOTE FACILITY 


The backquote facility defines two characters with special 
Syntax to the Lisp reader: backquote (*--ASCII code 140) and 
comma (,-~ASCII code 54). These two "macro characters" can be 
used together to abbreviate large compositions of functions like 
cons, list, list*, and append. It is typically used to specify 
templates for building code or other list structure and often 
finds application in the construction of Lisp macros. 


If you are in Emacs, backquote is automatically defined 
correctly for you. ESC-ESC, LISP mode, and LDEBUG mode all 
handle it properly. If you write extension code that uses 
Zinclude e-macros.incl.lisp (as all extension code should), 
backquote is defined properly for you as well. If you are 
writing Lisp code other than Emacs extensions, your program 
should inciude the form (%include backquote) before the first use 
of backquote. 


Backquote has a syntax similar to that of quote ('-~ascii 
47). A backquote is followed by a single expression. If the 
expression does not contain any use of the comma macro character, 
then the form will simply be quoted. For example: 


‘(a bc) => (quote (a bc)) => '(a boc) 


The comma macro character can only be used within a form 
Following a backquote. Comma also has a syntax like that of 
quote. The comma is followed by a form, and that form.is 
evaluated even though it is inside the backquote. For example: 


*(,a be) => (cons a (quote (bc))) 
=> (cons a '(bc)) 

Sa. be) (list* (quote a) b (quote (c))) 

> (list* 'a b '(c)) 


oat 
Vv 
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‘(a b,c) => (list (quote a) (quote b) c) 
=> (list 'a 'bc) 


‘(a . ,rest) => (cons (quote a) rest) 
=> (cons ‘a rest) 


Thus, to write the common macro "push" using backquote, proceed 
from the standard definition: 


(defun push macro (form) 
(list '‘setq (caddr form) (List ‘cons (cadr form)(caddr form 


tos 


(defun push macro (form) 
*“(setq ,(caddr form) (cons ,(cadr form) ,(caddr form)))) 


Note how the code to build the macro's output code begins to look 
more like the output code itself. In fact, using let, you can go 
all the way to: 


(defun push macro (form) 
(let ((datum (cadr form)) 
(list (caddr form))) 
‘(setq ,list (cons ,datum ,list)))) 


-~ 


and produce very legible code. 


Backquote expands into forms that call cons, list, list*, or 
whatever other functions it deems appropriate for the task of 
constructing a form that looks like the one following the 
backquote, but with the values of the forms following the commas 
substituted in. 


If acomma inside a backquote form is followed by an at 
Sign (@-- ASCII code 100), then the form following the ",@" 
should return alist. Backquote arranges that the elements of 
that list will be substituted into the resulting list structure. 
Frequently this involves generating a call to the append 
function. For example: 


*(,@a bc) => (append a (quote (bc))) 
=> (append a '(bc)) 


‘(a ,@b c) => (cons (quote a) (append b (quote (c)))) 
=> (cons 'a (append b '(c))) 


“(a Bb ,@c) => (list* (quote a) (quote 6b) c) 
=> (list* 'a 'b oc) 
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Similar to following the comma by an at sign is following 
the comma by a dot (.--ASCII code 56). The dot is a declaration 
to backquote telling it that the list returned by the form 
following the ",." is expendable. This allows backquote to 
produce code that calls functions like ncone that rplac the list. 


Backquote examines the forms following the commas to see if 
it can simplify the resulting code. For example: 


‘(a b. ,({cons x y)) => (list* (quote a) (quote b) x y) 
=> (list* 'a 'b x y) 


‘(a 3 ,be¢ ,17) => (list* (quote a) 3 b (quote (c 17))) 
=> (list* ‘a 3 b '({c 17)) 


‘(a ,@b ,@nil) => (cons (quote a) b) 
=> (cons ‘a b) 


‘(a ,.b ,@(ncone ¢ d)) => (cons (quote a) (nceone be d)) 
=> (cons ‘a (ncone be d)) 


These examples should convince you not to depend on what the 
code that backquote expands into will look like. Backquote's 
contract is specified not in terms of the code that it expands 
into but rather in terms of what that code produces when 
evaluated. A simple backquote might expand (,@a ,@nil) into 
(append a ‘'nil), but this cannot be used as a reliable way to 
copy a list since a sophisticated backquote (like this one) can 
optimize the copying away. 


It is sometimes useful to nest one use of backquote within 
another. This might happen when writing some code that will cons 
up some more code that will in turn cons up yet more code. The 
usual example is in writing macro-defining macros. When this 
becomes necesSary it is sometimes difficult to determine exactly 
how to use comma to cause evaluation to happen at the correct 
times. The following example exhibits all the useful 
combinations: 


*“*(a ,b ,,¢ ,',@) Pe ce . ee 
=> (list 'list* ‘'a ‘pc (list ‘quote (list d))) 
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When evaluated once, this yields: 
(list* 'a b <c-at-time-1> '(<d-at-time-1>)) 
Which when evaluated yields: 
(a <brat-time-2> <<c-at-time-1>-at-time-2> <d-at-time-i>) 


Thus *" means never evaluate, ",” means evaluate only the second 
time, ™,,™ means. evaluate both times, and ",',”™ means evaluate 
only the first time. 
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APPENDIX B 


QUICK REFERENCE 


The following functions, special forms, predicates, and 
global variables mentioned in this manual have been grouped below 
according to the uses they serve in extensions. Following those 
groupings is an alphabetized list that includes a brief 
description of each function, special form, predicate and global 
variable listed. The categories include: 


Buffers 

Calculations 

Catenation 

Character/Numeric Conversion 
Charscan Table/Characters 
Comments 

Comparison 

CTL 

Debugging 

Defining/Calling a a ca a ia 
Displays 

Error Handling 
Execution and Conditional Evaluation 
Files 

Killing 

List Processing/Cons 

Marks 

Minibuffers/Prompts 

Modes 

Modified Flag 

Multics Command Execution 
Point Position 

Searching 

Variables 

Whitespace 

Windows 

Miscellaneous 
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Buffers 


buffer-creation-hook 
buf fer-destruction-hook 
buffer-entrance-hook 
buf fer-exit-hook 
buffer-kill 
buffer-minor-modes 
buffer-modified-flag 
buffer-on-display-in-window. 
current~buffer 
current~buffer-mode 
destroy~buffer-contents 
display-buffer-as-printout 
dont-notice-modified-buffer 
empty-buffer-p 
establish-local-var 
find-buffer-in-window 

. £Eind-file-subr 
go-to-or-create-buffer 
previous~-buffer 
read-only-flag 
Save-excursion-buffer 
select-buffer-find-window 
select-buffer-window 
set-~buffer-self-destruct 


Calculations 


& 
+ 


// 


Catenation 


apply-catenate 
catenate 


Character/Number Conversion 


*nopoint 
ascii 

base 

Ctol 
decimal-rep 
ibase 

ITtoc 
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Character Table/Characters 


charscan-table 
charset-member 
explode 
explodec 
get-char 
lefthand-char 
process-char 


search-back-first-charset-line 
search-back~-first-not-charset-line 


search-charset~-backward 
search-charset-forward 
search-for-first~charset-line 


search-for-first-not-charset-line 


search-not-charset-backward 
search-not-charset~-forward 


Comments 


comment-column 
comment-prefix 


Comparison 


CTL 


OWVIA 


samepnamep 


DCTL-clear-rest-of-screen 
DCTL-~delete-chars 
DCTL-delete-lines 
DCTL-display-char-string 
DCTL-epilogue 

DCTL-init 
DCTL-insert-char-string 
DCTL-~insert-lines 
DCTL-kill-line 
DCTL-~position-cursor 
DCTL-prologue 
DCTL-~scroll-down-region 
DCTL-scroll-up-region 
Rprinc 

Rtyo 
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Debugging 


debug-e 
ldebug-mode-hook 


Defining/Calling a Command/Function/Property 


defcom 

defprop 

defun 

funcall 

get 

orocess~char 
putprop 

set-key 
set-permanent-key 


Displays 


display-as-printout | 
display-buffer-as-printout 
display-com-error 
display-com-error-noabort 
display-error 
display-error-noabort 
display-error-remark 
end-local-displays 
full-redisplay 
init-local-displays 
local-display-current-line 
local-display-generator 
local-display-generator-nnl 
redisplay 
redisplay-current-window-relative 
view-region-as-lines 


Error Handling 


add_error_code 
command-quit 
display-com-error 
display-error 
display-error-noabort 
display-error-remark 
error-table 

error _table_ 
report-error 
report-error-noabort 
ring-tty-bell 
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trace 
unwind-protect 


Execution and Conditional Evaluation 


and 

cond 
dispatch-on-current-char 
dispatch-on-lefthand-char 
do 

do-forever 

do-times 

eval 

funcall 

go 

if 

if-at 

if-back-at 

mapc 

or. 

prog 

progi 

prog2 

progn 

return 

Save-excursion 
Save-excursion-buffer 
Save-excursion-on-error 
stop-doing 
unwind-protect 
without-modifying 
without-Saving 


Files 
find-file-subr 
fpathname 


read-in-file 
write-out-file 
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Killing 
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buffer-destruction-hook 
buffer-kill 
delete-white-sides 
delete-window 
destroy-buffer-contents 
killsave-string 

kill-pop 

killi-ring=top 
rotate-kill-ring 
set-buffer-self-destruct 
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wipe-point-mark 
without-saving 


List Processing/Cons 


append 
apply-catenate 
car 

edr 
cons 
explode 
explodec 
list 
list* 
memq 
nconc 
nreverse 
reverse 
replaca 
replacd 


Marks 


der-wahrer-mark 
go-to-mark 
mark-at-current-point-p 
mark-on-current-~line-p 
mark-reached 
mark~-same-line-p 
point~mark-to-string 
point>markp 
release-mark 

set-mark 
wipe-point-mark 
with-mark 


Minibuffers/Prompts 


last-minibuffer-response 
minibuffer-response 
minibuffer-clear 
minibuffer-print 
minibuffer-print-noclear 
yesp 


Modes 


alm-mode-hook 
assert-minor-mode 
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buf fer-minor-modes 
current-buffer-mode 
fill-mode-delimiters 
fortran-mode-hook . ) 
ldebug-mode-hook 
lisp-mode-hook 
mail-mode-hook 
negate-minor-mode 
pli-mode-hook 
rmail-mode-hook 
text-mode-hook 


Modified Flag 


buffer-modified-flag 
dont-notice-modified-buffer 
read-only-flag 
without-modifying 


Multics Command Execution 


comout-get-output 
e_cline_ 


Point Position 


at 
at-bDeginning-of-buffer 
at-end-of-buffer 
at-white-char 
back-at 

_bolp 
cur-hpos 
curchar 
eolp 
firstlinep 
go-to-hpos 
go-to-mark 
if-at 
if-back-at 
lastlinep 
looking-at 
mark-at-current-point-p 
next-line 
point-mark-to-string 
point>markp 
prev-line 
Save-excursion 
save-excursion-on-error 
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Searching 


charscan-table 

forward-search 

get-search-string 

regexp-search 
reverse-regexp-search 
search-back-first-charset-line 
search-back-first-not-charset-line 
search-charset-backward 
search-charset-forward 
search-failure-annunciator 
search-for-first-charset-line 
search-for-first-not-charset-line 
search-not-charset-backward 
search-not-charset-forward 


Variables 


defvar 
establish-local-var 

let 
register-local-variable 
setq 


Whitespace 


at-white-char 
delete-white-sides 
Format-to-col 

line-is-blank 
skip-back-to-whitespace 
skip-back-whitespace 
skip-back-whitespace-in-line 
skip-over-whitespace 
Skip-over-whitespace-in-line 
skip-to-whitespace 
tab-equivalent 
whitespace-to-hpos 


Windows 


buffer-on-display-in-window 
delete-window 
Find-buffer-in-window 

nuwindows 
redisplay-current-window-relative 
select-buffer-find-window 
select-buffer-window 
select-window 

selected-window 
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window-adjust-lower 
window-adjust-upper 
window-info 


Miscellaneous 


what 


close-line-hook 
env-dir 

ESC 
fill-mode-delimiters 
insert-string 
maknam 

nil 

NL 

not 

null 
null-stringp 
print 
process-dir 
read-from-string 
ring-tty-bell 
stringp 

symbolp 

c 


yesp 


Bach item described below also has a note that indicates 


type of item it is. 


The item types are: 


Native Lisp function, variable, predicate, or special form 

Emacs environment function, variable, etc. 

CTL functions, to be defined by CTL writer, called by 
Emacs Redisplay, and not called by extension code under 


any circumstances. 


Lisp function 
takes any number of 
fixnums (integer numbers), and returns their product. 


arguments, which are expected to be 


*nopoint Lisp global variable : 
when bound to anything but nil, causes decimal numbers to be 
converted to their printed representation without a trailing 


+ 


decimal point. 


Lisp function 


adds any number of fixnum arguments. 


B-9 . CJ52-01 


= Lisp function 
Subtracts all of its (fixnum) arguments but the first from 
its first argument. With two arguments, it simply computes 
the difference. 


// Gisp function 
divides its first (fixnum) argument successively by each of 
its succeeding arguments. Answer is a whole number 
(fixnum). With two arguments, it is a simple integer 
quotient. . 


predicate 


of two arguments, fixnums. Returns truth if first is less 
than second. 


A 
tt 
rt) 
"3 


= Lisp predicate 
of two arguments, fixnums. Returns truth if they are the 
same fixnum. 


> Lisp predicate 
of two arguments, fixnums. Returns truth if the first is 
greater than the second. . 


add-error-code Emacs function 
of two arguments, error-code and error-string, adds an entry 
to the Emacs Error Table. 


alm-mode-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
_ upon entering ALM mode ina buffer. Used to customize key 
' bindings, etc. | 


alphalessp Lisp predicate | 
of two arguments, can be symbols or strings. Returns truth 
if the printname (or string value) of the first collates 
alphabetically in the ASCII collating sequence before the 
second. 


and Lisp special form 
evaluates all of its subforms in order until one of them 
evaluates to nil, or they are all evaluated. The value 
returned by the last one evaluated is returned. 


append Lisp function 
takes any number of lists as arguments, including empty 
lists. Returns a list with all the elements of the lists 
provided as elements, in order. 


apply-catenate Emacs function 
takes a list of any number of strings or symbols, and 
returns a string that is the catenation of all their string 
values or printnames. 
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ascii Lisp function . 
returns a sSingle-character symbol whose printname is the 
character whose ASCII numeric value waS given as an 
argument. | 


assert-minor-mode Emacs function 
of one argument, asserts that this minor mode (expected to 
be a symbol) has been turned on. It appears in the mode 
line in the current buffer. 


at Emacs predicate 
of one argument, a single-character string or symbol. 
Returns truth if the character to the right of point in the 
current buffer is this character. 


at-beginning-of-buffer Emacs predicate | 
returns truth if the current point in the current buffer is 
at the beginning of the buffer. 


at-end-of-buffer Emacs predicate ° 
returns truth if the current point in the current buffer is 
at the end of the buffer. 


at-white-char Emacs predicate 7 
returns truth if the character to the right of the current 
point in the current buffer is a whitespace character. 


back-at Emacs predicate 
of one argument, a single-character string or symbol, 


returns truth if the character to the LEFT of point in the 


current buffer is this character. 


base Lisp global variable 
normally 8, the binding of the variable controls the numeric 
base in which numbers are converted to their printed 
representation. 


bolp Emacs predicate 
returns truth if the current point in the current buffer is 
at the beginning of a line, | 


buffer-creation-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function when a buffer 1s created. 


buffer-destruction-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function when a buffer is destroyed. 


buffer-entrance-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function when a new buffer is 
selected. 
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buffer-exit-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function when a. buffer is left. 


buffer-kill Emacs function 
of one argument, the symbol representing a buffer. Destroys 
that buffer. 


buffer-minor-modes Emacs per-buffer variable 
the list of symbols that have been asserted and not negated 
as the current minor modes in the current buffer. 


buffer-modified-flag Emacs per-buffer variable 
value is non-nil if the current buffer has been modified 
Since last read in or written out. Do not set this flag by 
yourself; let Emacs manage it. 


buffer-on-display-in-window Emacs predicate 
.aS a predicate, returns truth if the buffer whose symbol is 
provided as an argument is currently on display in any 
window... 


buffer-on-display-in-window Emacs function 
as a function, returns the vindow number in which the buffer 
provided is on display (or nil if none). 


car Lisp function 
returns the "car" of the argument, which is expected to be a 
cons. Note that for conses which are parts of lists, car 
may be viewed as returning the first element of the list. 


catenate Lisp function 
given any number of strings or symbols as arguments, returns 
a string that is the catenation of their string-values or 
printnames. 


cdr Lisp function 
returns the "cdr" of the argument, which is expected to be a 
cons. Note that for conses that are parts of lists, cdr may 
be viewed as returning a list of all the elements beyond the 
first element. 


charscan-table Emacs function 
takes a character-string argument, and creates a charscan 
table that can be used to search a string for those 
characters. 


charset-member Emacs function 
the first argument is a single character st 
or fixnum that is the ASCII value of a ch 
second argument is a charscan table. Retur 
character is a member of that charscan table. 


ig, v« symbol, 
ter, and the 
truth if the 
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close-line-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function when the user moves to 
another line. 


command-quit Emacs function 
aborts the execution of the current extension function, 
beeping, and returning to the Emacs character-listening 
loop. 

comment-column Emacs per-buffer variable 
the zero-based comment column in the current buffer. 


comment-prefix Emacs per-buffer variable 
the string to be inserted at the start of comments in this 
buffer, and searched for to find the start of already 
existent comments. 


comout-get-output Emacs function | 
catenates all of its arguments into a Multics command line, 
and replaces the contents of the current buffer by the 
Multics output produced by executing that Multics command 
line. 


cond Emacs special form 
performs successive tests of conditions and conditionally 
executes forms. Specifically, evaluates the first subform 
of all of its own subforms, until one returns non-nil, and 
executes all the remaining subforms of that subform (of 
cond), returning the value of the last subform, of any kind, 
evaluated. See the writeup/examples. 


cons Lisp function 
constructs a new cons, whose car and cdr are the two 
arguments given. 


CtoI Lisp function 
obtains the numeric ASCII value of the character that is the 
printname (if a symbol, or value if a string) of its 
argument. 


cur-hpos Emacs function 
the zero-based current horizontal position of point on the 
current line in the current buffer. Note that this is 
horizontal position onan infinite-width line-printer or 
printing terminal, not on the screen. Tabs count, 
backspaces count, etc. 


curchar Emacs function 


returns the sSingle-character symbol whose .printname is the 
character to the right of point in the current buffer. 
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current-buffer Emacs per-buffer variable 
the symbol representing the current buffer. 


current-~buffer-mode Emacs per-buffer variable 


the symbol representing the major mode in the current 
buffer. 


DCTL-clear-rest-of-screen CTL function 
clear to the end of the screen from the cursor. 


DCTL-delete-chars CTL function 
delete n (argument) characters at the cursor, shifting the 
rest of the line over to the left. . 


DCTL-delete-lines CTL function 


delete n (argument) lines from the screen at the cursor, 
moving the rest of the lines on the screen up. 


DCTL-display-char-string CTL function 
print the character string supplied as an argument at the 
cursor, moving the cursor to the end. 


DCTL-epilogue CTL function 
take appropriate actions to "reset" the terminal from Emacs 
mode to normal Multics mode. 


DCTL-init CTL function 
set up the CTL to operate and then clear the screen. 


DCTL-insert-char-string CTL function 
insert the character-string argument at the cursor, pushing 
the rest of the line over to the right. 


DCTL-insert-lines CTL function 
epen up n (argument) blank lines at the cursor pushing the 
rest of the lines down, the n lowest off the screen. 


DCTL-kill-line CTL function 
clear from the cursor to the end of the line. 


DCTL-~position-cursor CTL function 
takes x, y aS arguments. Move the cursor (if not already 
there) to that position; x and y are zero based. 


DCTL-prologue CTL function 
ready the CTL for Emacs usage as opposed to Multics normal 


mode. 
DCTL-scroll-down-region CTL function 
scroll a reqion at the cursor down. 


DCTL-scroll-up-region CTL function 
scroll a region at the cursor up. 
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debug-e Emacs function 
sets error traps in Emacs so that extension code bugs 
breakpoint in Lisp. 


Gecimal-rep Emacs function 
converts its (numeric) argument toa string that is its 
decimal representation. 


defcom Emacs special form 
defines a command. 


defprop Lisp special form 
puts a property on a symbol. Like putprop, but is a special 
form and does not evaluate any of its arguments. 


defun Lisp special form 
defines a function. 


Gefvar Emacs special form 
declares a special variable (first argument, not evaluated) 
and assigns a value if the variable has not been set when 
the program is loaded (second argument, evaluated). 


delete-white-sides Emacs function 
removes all whitespace characters on either side of point in 
the current buffer. 


delete-window Emacs function 
destroys the window whose window number is given. 


Gder-wanrer-mark Emacs per-buffer variable 
"the true mark,” i.e., the user-visible (*@) mark in the 
current buffer. 


destroy-buffer-contents Emacs function 
destroys the contents of the current buffer. 


dispatch-on-current-char Emacs special form 
executes forms conditionally based upon the value of the 
character to the right of point in the current buffer. 


dispatch-on-lefthand-char Emacs special form 
executes forms conditionally based upon the value of the 
character to the right of point in the current buffer. 


display-as-printout Emacs special form 

| displays as local display all of the text placed in the 
current buffer (which will be created by this form) by the 
forms contained in it. 


display-buffer-as-printout Emacs function 
displays the current buffer as local display. 
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display-com-error Emacs function 
takes a Multics error code argument and strings that are 
catenated to produce an error message in the minibuffer 
(including the converted Multics error code), aborts the 
current extension code execution, and beeps. 


display-com-error-noabort Emacs function 
like display-com-error, but does not abort. 


display-error Emacs function : 
catenates its string arguments to produce an error message 
in the minibuffer, aborts the current extension code 
execution, and beeps. 


display-error-noabort Emacs function 
like display-error, but does not abort. 


display-error-remark Emacs function 
like display-error-noabort, but this output is suppressed 
during keyboard macro execution. 


do Lisp special form 
complex native Lisp form for iterated execution. 


do-forever Emacs special form 
executes all of the forms contained within it until they 
return or abort of their own accord. 


do-times Emacs special form 
first form is evaluated to obtain a number; the rest of the 
forms are executed that many times. 


dont-notice-modified-buffer Emacs function 
argument is a buffer-symbol. If called, that buffer's being 
modified does not prevent the user from exiting Emacs 
without being queried. 


e cline _ Emacs function 
executes a Multics command line (the supplied string) 
without any arrangements for 1/0, etc. 


empty-buffer-p Emacs predicate 
returns truth if the buffer-symbol argument represents an 
empty buffer. 


end-local-displays Emacs function 
indicates that a local display has produced all it is going 
to, and the next charater typed by the user should erase the 
local display. 


env-dir Emacs global variable 
the directory in which the Emacs subsystem is located. 
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eolp Emacs predicate 
returns truth if the current point in the current buffer is 
at the end of a line. | 


eq Lisp predicate 
returns truth if the same object is given as both arguments. 


error-table Emacs function 


of two arguments, segment and offset, gets a standard j 


Multics error code. 


error_table_ Emacs function 
produces a Multics error code given an error table entry 
point name as a string or symbol. 


ESC Emacs global variable 
a single-character symbol whose name is the ESC character. 


establish-local- var Emacs function 
declares a buffer local variable sua establishes a value. 


eval Lisp function 
evaluates a Lisp form. 


explode Lisp function 
creates a list of characters (single-character symbols) that 
is the standard Lisp printed representation of its argument. 


explodec Lisp function 
like explode, but does not escape Lisp special characters or 
quote strings. 


fill-mode-delimiters Emacs global variable | 
the list of characters that cause fill mode to fill. 


find-buffer-in-window Emacs function 


takes a buffer-symbol argument, and either selects a window 


containing that buffer, or first puts it somewhere other 
than the current window (on an LRU basis) and then selects 
that window. 


find-file-subr Emacs function 
takes an argument like those acceptable to “X“F, and does as 
AXAF does (reads file or files, selects buffers, etc.). 


firstlinep Emacs predicate . 
returns truth if the current point is on the first line of 
the current buffer. 


fixp Lisp predicate 
returns truth if its argument is a fixnum (or bignum). 
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format-to-col Emacs function 
puts whitespace in the current line at the current point, 
putting in at least one space. The argument is the column 
(zero-based) to format out to. 


fortran-mode-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering FORTRAN mode ina buffer. Used to customize 
key bindings, etc. 


forward-search Emacs function 
takes a string (or symbol) argument. Searches foward (as 
does *S) in the current buffer, returning truth if the 
Search succeeds (and moving point) or nil if not. 


fpathname Emacs per-buffer variable 
pathname (or nil if none) of file in current buffer. 


full-redisplay Emacs function 
clears the screen and redisplays all windows. 


funcall Lisp function 


calls a function (the first argument) upon all the rest of 
its arguments. Needed only when the identity of the 
function to be called is not known, i.e., was obtained from 


the value of a variable. 


get Lisp special form 
first argument is a symbol, second a property. Obtains that 
property of that symbol, or nil if it hasn't one. 


get-char Emacs function 
returns (as a fixnum ASCII value) a single character read 
from the keyboard (or keyboard macro). Does not echo or 
prompt in any way. 


get-search-string Emacs function 
takes a prompt string. Gets a search string from the user 
(for use in writing search requests), and does defaulting 
and setting of defaults. 


go Lisp special form 
transfers to a PROG label. 


go-to-hpos Emacs function 
moves the current point to the character that would be at 
that (argument) horizontal position (see cur-hpos fora 
definition of horizontal position). 


go-to-mark Emacs function 


argument is amark that must be in the current buffer. 
Moves point to that mark. 
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go-to-or-create-buffer Emacs function 
argument is a buffer symbol. Goes to that buffer, creating 
it if it does not exist. If it did exist, point will be 
where it last was in that buffer. 


ibase Lisp global variable 
base (normally 8) for converting numbers typed into Lisp. 


HE Emacs special form 
special form for conditional execution. Evaluates its first 
form. If non-nil, evaluates all following forms up to 
"else" or end of the "if"; otherwise, evaluates all forms 
after the "else" (if any). 


if-at Emacs special form 
first argument is a character symbol or string. Evaluates 
all the rest of its forms if the current character at the 
right of the point in the current buffer is this character. 


if-back-at Emacs special form 
Same as if-at, but for the character to the left of the 
point. 


init-local-displays Emacs function 
sets up for local display output. 


insert-string Emacs function 
of one argument, a string (or symbol) of any length. 
Inserts those characters to the left of the current point 
(thus moving it} in the current buffer. 

ItoC Lisp function 
creates a single-character string from the ASCII value given 
as an argument. 


eaieayer string Emacs function 
pushes its string (or symbol) argument onto the kill rind. 
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kill-pop Emacs function 


Ral 


returns the first item on the kill ring and rotates the kill 
ring. 


ring-top Emacs function 
returns the first item on the kill ring. 


lastlinep Emacs predicate 


last- 
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returns truth if the current point is on the last line of 
the current buffer. If there is a newline in the file, this 
means the line (which may be empty) immediately after the 
last newline. 


minibuffer-response Emacs per-buffer variable 

The last response given in the minibuffer. When ESC X opt 
remember-empty-response is set off, last-minibuffer-response 
is not set to blank when a blank response is given. 
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ldebug-mode-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering LDEBUG mode in a buffer. Used to customize 
key bindings, etc. 


lefthand-char Emacs function 
returns a single character symbol whose printname is the 
character to the left of point in the current buffer. 


let Lisp special form 
‘establishes. variables and their bindings for a computation. 


line-is-blank Emacs predicate 
returns truth if the current line of the current buffer (the 


one on which point is) has no characters, or only whitespace 
characters. 


lisp-mode-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering LISP mode in a buffer. Used to customize key 
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list Lisp function 
returns a list whose elements are list's arguments. 


list* Lisp function 
returns a list-like chain of conses, whose first n-i 
elements are list*'s first n-1l arguments, but the cdr of 
whose last cons is list*'s nth and last argument. 


local-display-current-line Emacs function 
displays the current line of the current buffer as local 
display (a local display must already have been 
established). 


local-display-generator Emacs function 
takes a string (which must end in a newline) and displays it 
as local display. 


local-display-generator-nnl Emacs function 
like local-display-generator, but adds the newline for you. 


looking-at Emacs predicate 

. returns truth if the string given as an argument (which must 
not contain a newline) appears immediately to the right of 
the current point in the current buffer. 
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mail-mode-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol . 
that can be called as a function as the last action of Emacs 
upon entering MAIL mode in a buffer. Used to customize key 
bindings, etc. 


maknam Lisp function 
makes a new symbol, not interned, whose name is formed from 
the supplied list of characters (symbols or fixnums, the 
latter interpreted as specifying ASCII values). 


mape Lisp function 
an iterator; first argument specifies a function. Second 
through last arguments are lists. The function is marched 
through the elements of the lists, in parallel. 


Mark-at-current-point-p Emacs predicate 
takes a mark as argument. Returns truth if that mark 
specifies the place in the current buffer where the current 
point is. 


mark-on-current-line-p Emacs predicate 
takes a mark as argument. Returns truth if that mark 
specifies a point on the same line of the current buffer 
where the current point is. 


mark-reached Emacs predicate 
takes a mark as argument. Returns truth if current point 
has passed this mark in the current buffer. There are 
reStrictions on this (see the writeup). 


mark-same-line-p Emacs predicate 
takes two marks as arguments. Returns truth if they 
represent points on the same line. 


memq Lisp predicate 
returns truth if its first argument is a member of the list 
that is its second argument. 


mintouhereeiearcait Emacs function 
no:arguments, completely clears the minibuffer. 


mMinibuffer-response Emacs function 
takes two arguments; the first is a prompt string, and the 
second is either NL or ESC - prompts the user with that 
string in the minibuffer, requiring that termination 
character. Returns the string result of the user's typing. 


minibuffer-clear Emacs function 
clears the current line of the minibuffer. 
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minibuffer-print Emacs function 
takes any number of arguments, expected to be strings or 
symbols, catenates and prints them in the minibuffer. 


minibuffer-print-noclear Emacs function 
like minibuffer-print, but appends these sSEEInG= to the last 
active line of the minibuffer. 


neonc Lisp function 
like append, but destructively rethreads its arguments to 
produce its result. Be careful to utilize the result value 
of neconc. 


negate-minor-mode Emacs function 
asserts that a minor mode (specified by its symbol.argument) 
is no longer in effect in the current buffer. The mode is 
removed from the mode line at the next redisplay. 


next-line Emacs function 
places the current point in the current buffer at the 
beginning of the next line in that buffer. 


nil Lisp global variable 
its value is itself, nil, which is both the indicator of 
falsity and the emtpy list. 


NL Emacs global variable 
a symbol whose printname is an ASCII newline character. 


not Lisp predicate 
returns truth if its argument is the symbol "nil". 


nreverse Lisp function . 
like reverse, but destructively rethreads the list it is 
given. Be careful to use the return value of nreverse. 


null Lisp predicate 
returns truth if its argument is the symbol "nil". 


null-stringp Emacs predicate 
returns truth if its argument is a null string or the symbol 
whose printname has no characters. 


nuwindows Emacs per-buffer variable 
the number of windows on the screen (not including 
minibuffer or mode line). 


or Lisp special form 
evaluates all of its subforms sequentially nea? one is 
evaluated to anything but nil, or its las subform is 
evaluated, whichever comes first. Returns one “last form it 
evaluates. 
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pli-mode-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering PL/I mode in a buffer. Used to customize key 
bindings, etc. 


point-mark-to-string Emacs function 
returns as a string a copy of all text between the mark 
given aS an argument and the current point in the current 
buffer. 


point>markp Emacs predicate 
takes a mark as an argument. Returns truth if the current 
point is further on in the buffer than the place represented 
by that mark. 


prev-line Emacs function 
moves the point to the beginning of the previous line of the 
current buffer. 


previous-buffer Emacs per-buffer variable 
the symbol of the previous buffer Emacs was in. 


print Emacs function 
prints out (to normal Multics output) the printed 
representation of its argument. 


process-char Emacs function 


called on a fixnum that is an ASCII character 
representation, interprets that character (including reading 
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more, if necessary) as an Emacs request. 


process-dir Emacs global variable 
the pathname (a character string) of the process directory 
of the process using Emacs. 


prog Lisp special form 
sequentially evaluates forms within it, allowing use of 
local variables and labels. Returns nil, or the value 
Supplied to "return” 


progi Lisp special form 
evaluates sequentially all of the forms within it, returning 
the value of the first. 


prog2 Lisp special form 
evaluates sequentially all of the forms within it, returning 
the value of the second. 


progn Lisp special form 


evaluates sequentially all of the forms within it, returning 
the value of the last. 


B-23 CJ52-Q01 


protect Lisp special form 
evaluates and returns the value of its first subform. The 
remaining forms are then evaluated according to the success 
or failure of the first form's evaluation, as specified by 
special clauses. 


putprop Lisp function 
puts its second argument as the property specified by its 
third argument on its first argument, which must bea 
symbol.. 


read-from-string Lisp function 


performs a Lisp "reaG™ operation on the contents cof the 
String supplied, creating (or finding) and returning the 
Lisp object whose printed representation was specified by 


the string. 


read-in-file Emacs function 
takes a pathname argument; reads it into the current buffer. 


read-only-flag Emacs per-buffer variable 
when set (when buffer-modified-flag has not yet been set) 
prevents a user from modifying the buffer. For 
pseudo-editable displays (like DIRED). 


redisplay Emacs function 
updates the screen to reflect all changes in buffers on 
display. 


redisplay-current-window-relative Emacs function 
takes a line number on which to position the current line of 
the current buffer in the current window, where it is 
assumed to be on display. What “L with an argument does. 


regexp-search Emacs function 
like forward-search but does a "regular expression” search 
(as ESC / does). 


register-local-variable Emacs function 
sets up a per-buffer variable. 


register-option Emacs function 
sets up an Emacs user option. First argument is a symbol 
(that is the option name and variable) and second argument 
is a default value. 


release-mark Emacs function 


takes amark as an argument. Invalidates that mark, and 
frees Emacs from having to manage it any more. 


B-24 CJ52-01 


report-error Emacs function 
of two arguments, error-code and error-information, aborts 
the current computation and prints an error. 


report-error~noabort Emacs function 
of two arguments, error-code and error-information, prints 
an error without aborting. 


return Lisp function 
returns a value from a do, prog, do-times, or do-forever. 


reverse Lisp function 
takes a list as an argument, returns a list with the same 
elements but in opposite order. 


reverse-regexp~Ssearch Emacs function 
like reverse-search but does a "regular expression” search. 


reverse-search Emacs function 
searches backward for its (string or symbol) argument from 
the current point in the current buffer, as does “R (which 
uses it). Returns truth and moves point to before this 
string if the search succeeds. 


ring-tty-bell Emacs function 
beeps the tty bell. 


rmail-mode-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering RMAIL mode in a buffer. Used to customize key 
bindings, etc. 


rotate-kill-ring Emacs function 
rotates the kill ring. 


rplaca Lisp function 
first argument is a cons, the second is anything else. The 
second argument is made to be the car of the cons, which is 
returned as a value. 


rplacd Lisp function 
first argument is a cons, the second is anything else. The 
second argument is made to be the cdr of the cons, which is 
returned aS a value. 
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Rprinc Emacs function 


Rtyo 
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to be used only by CTLS; "sends" a character string in raw 
mode to the terminal. This function does not work unless 
invoked by the CTL at redisplay time. 


Emacs function 

to be used only by cCTLS; "sends" a single character, 
specified by numeric ASCII value, in raw mode to the 
terminal. This function does not work unless invoked by the 
CTL at redisplay time. , 
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Samepnamep Lisp predicate 
returns truth if both arguments are symbols of the same 
printname, or strings of the same character-string value. 


Save-excursion Emacs special form ; 
remembers where the point was in the current buffer when it 
was invoked, and restores it to there after evaluating the 
forms within. The value of save-excursion is the value of 
its last evaluation.. 


save-excursion-buffer Emacs special form 
remembers what buffer it was in when invoked, and restores 
Emacs to be in that buffer when exited after evaluating the 
forms within. 


Save-excursion-on-error Emacs special form 
remembers where the point was in the current buffer when it 
was invoked, and restores it to there if an error occurs 
while evaluating the forms within. 


search-back-first-charset-line Emacs function 
takes a charscan table as an argument. Scans backward in 
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a character in this charscan table. Returns truth and moves 
point if it succeeds. 


search-back-first-not-charset-line Emacs function 
takes a charscan table as an argument. Scans backward in 
the current line until the current point is to the right of 
a character not in this charscan table. Returns truth and 
moves point if it succeeds. 


search-charset-backward Emacs function ° 7 
takes a charscan table as an argument. Scans backward in 
the current buffer until the current point is to the right 
of a character in this charscan table. Returns truth and 
moves point if it succeeds. 


search-charset-forward Emacs function 
takes-a charscan table as an argument. Scans forward in the 
current line until the current point is to the left of a 
character in this charscan table. Returns truth and moves 
point if it succeeds. - 


search-failure-annunciator Emacs function . 
indicates that a search has failed, beeps, and aborts. To 
be used by search requests. 


search-for-first-charset-line Emacs function 
takes a charscan table as an argument. Scans forward in the 
current line until the current point is to the left of a 
character in this charscan table. Returns truth and moves 
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search-for-first-not-charset-line Emacs function 
takes a charscan table as an argument. Scans forward in the 
current line until the current point is to the left of a 
character not in this charscan table. Returns truth and 
moves point if it succeeds. 


search-not-charset-backward Emacs function 
takes a charscan table as an argument. Scans backward in 
the current buffer until the current point is to the right 
of a character in this charscan table. Returns truth and 
moves point if it succeeds. 


search-not-charset-forward Emacs function 
takes a charscan table as an argument. Scans forward in the 
current buffer until the current point is to the left of a 
character not in this charscan table. Returns truth and 
moves point if it succeeds. 


select-buffer-find-window Emacs function 
tries to put a buffer on the screen. See the section on 
window management. 


select-buffer-window Emacs function 
takes a buffer symbol and a line count as argument, and 
tries to get that buffer on the screen, putting it in the 
current window if it is not now on the screen. See the 
section on window management. 


select-window Emacs function 
takes a window number as argument. Moves the cursor to 
(selects) that window. 


selected-window Emacs per-buffer variable 
the window number of the window in which the cursor 
currently appears. 


set-buffer-self-destruct Emacs function 
takes a buffer symbol as argument. After this function is 
used, that buffer will be destroyed the first time it is 
exited. 


set-key Emacs function 
assigns key bindings in the current buffer. Takes two 
arguments, the key name vi a string or symbol, and the 
function name via a symbol. The key name can be anything 
like the names in the documentation, e.g., *X, “x, ESC ESC, 
AXq, control-p, c-p, meta-f, ESC “f, etc. See Section 15 of 


acceptable key names. 
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set-mark Emacs function 
creates a@ mark at the point where the current point is in 
the current buffer, and maintains it thereafter. Be sure to 
release-mark such marks, or use with-mark. | 


set-permanent~-key, set perm-key Emacs function 
sets a key to invoke a function in all buffers. Like 
Sset-key, takes two arguments, the keyname via a string or 
symbol, and the function name, via a symbol. See Section 15 


setq Lisp special form 
assigns a value to a variable. 


skip-~back-to-whitespace Emacs function 
moves current point backward in current buffer until a 
whitespace character (or the beginning of the ‘buffer, 
whichever comes first) is to the left of it. . 


Skip-back-whitespace Emacs function | 
moves current point backward in current buffer until a 
non-whitespace character (or the beginning of the buffer, 
whichever comes first) is to the left of it. 


skip-back-whitespace-in-line Emacs function 
moves current point backward in current buffer untila 
non-whitespace character (or the beginning of the line, 
whichever comes first) is to the left of it. 


skip-over-whitespace Emacs function 
moves current point in current buffer forward over all 
whitespace characters until the first non-whitespace 
character. 


skip-over-whitespace-in-line Emacs function 
moves current point in current buffer forward over all 
whitespace until the end of the line. ‘ 


skip-to-whitespace Emacs function 
moves current point in current buffer over all 
non-whitespace characters until the next whitespace 
character, 


stop-doing Emacs special form 
causes do/do-forever to exit, returning nil. 


Stringp Lisp predicate . 
returns truth 1f its argument is a string. 


symbolp Lisp predicate 
returns truth if its argument is a symbol. 


B-28 CJ52-01 


: Lisp global variable 
its value is itself, which represents canonical truth. 


tab-equivalent Emacs per-buffer variable 
sets how many spaces a tab is "worth" (normally ten) in the 
current buffer. 


text-mode-hook Emacs global variable 
if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering TEXT mode in a buffer. Used to customize key 
bindings, etc. 


trace Lisp special form 
causes Lisp functions to be traced. 


unwind-protect Lisp special form : 
evaluates and returns the value of its first subform. The 
remaining subforms are evaluated after the first form's 
evaluation is finished, or when that first evaluation is 
aborted. This is how you set up a "cleanup handler" 


view-region-as-lines Emacs function 
displays the region in the current buffer as local display. 


whitespace-to-hpos Emacs function 
places whitespace, in optimal tabs and spaces, at the 
current point in the current buffer, moving it until the 
Specified (as argument) horizontal position has been 
reached. | 


window-adjust-lower Emacs function 
adjusts the lower boundary line of a window. First argument 
is window number, second is how much to move it, signed. 


window-adjust-upper Emacs function 
adjusts the upper boundary line of a window. First argument 
is window number, second is how much to move it, signed. 


window-info Emacs function 
returns a list of information about the window whose window 
number is given as an argument. 


wipe-point-rmark Emacs function 
takes a mark as argument. Deletes all text in the current 
buffer between the current point and this mark, saving it on 
the kill ring unless without-saving is being used. 


with-mark Emacs special form 
creates a mark in the current buffer at the place where the 
current point is when with-mark was invoked. The variable 
whose name appears first in the with-mark form is bound to 
this mark; with-mark frees this mark automatically. 
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without-modifying Emacs special form 
evaluates the forms within it, but the buffer is not marked 
as modified even though these forms may modify it. 


without-saving Emacs special form 
evaluates the forms contained within it, but the automatic 
Saving of killed text on the kill ring is suppressed. 


write-out~file Emacs function 


takes a pathname argument. Writes the current buffer out to 
that. file. 


yesp Emacs predicate 


takes a string argument. Asks the user that question in the 
minibuffer, and returns truth in response to a "yes" answer, 
rejecting all answers but "yes" or "no", 
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INDEX 


MISCELLANEOUS 


&arguments defcom keyword 
3-63, 3-6¢,- 3-66, 3-68, 
3-69 


&cleanup defcom keyword 3-66, 
3-68; 3769 


&completions defcom keyword 
3-66; 3-67 


&documentation defcom keyword 


&epilogue defcom keyword 3-65 
3-68, 3-69 


&inverse defcom keyword 3-67, 
3-68 | 


&negative-function 3-66 


&negative-function defcom 
keyword 3-68 


&numeric-argument defcom 
keyword 3-61, 3-62, 3-66 
3-68 


&numeric-function defcom 
keyword 3-62 


&prologue 3-66 


f 


v 


1 


&prologue defcom keyword 3-65, 
3-68 


&undo defcom keyword 3-67 
(*rset t) mode 3-48 

*nopoint global variable 2-19 
+ function 2-2 

-function 2-1 


/(Lisp escape character) 2-11 


//funetion 2-11 
< predicate 2-5 
= predicate 2-5 
> predicate 2-5 


add-error-code function 3-60 


addition 
+function 2-1 


alphalessp predicate 2-6 
and special form 2-i1 


append function 2-16 
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apply-catenate function 
3-31 


2718; 


ascii function 3-43 


assert-minor-mode function 
3-39 


at. predicate 3-12 
at-beginning-of-buffer 
predicate 3-it 


at-end-of-buffer predicate 
3-11 
at-white-char predicate 3-11 


attribute 
see symbol, property 


autophanic request 3-52 


B 
back-at predicate 3-12 
backquote 2-18, A-1 


base global variable 2-19 


binding. -2-3, -2-16 
bolp predicate 3-11 
breakpoint 4-4 
buffer 
dont-notice-modified-buffer 
3729 
ldebug 4-1 
nontemporary 3-28 
symbol 3-27, 3-52 
temporary 3-27 
buifter-creatinge 3-3, 3=26 


buffer-kill function 3-29 


buffer-minor-modes variable 
3-23, 37°39 


buffer-modified-flag variable 
3-22 . 


buf fer-on-display-in-window 
function 3-56 
predicate 3-56 


builtin function 
22-2 
list 2-14 
print 2-2 
rplaca 2-15 
rplacd 2-15 


car 2-13 


catenate function 3-31 
cdr 2-13 
character object 3-40 


character/number conversion 
s=43 


characters 


searching for 3-33 


charscan-table function 3-33 
charset-member predicate 3-34 


cleanup handler 
protect 3-10 


cleanup-handler 
unwind-protect 3-9 


command executing 
Multics 3-58 
command-quit function 3-18 


comment 2-1 
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comment-column variable 3-22 
comment-prefix variable 3-22 
comout-get-output 3-59 
compilation 3-48, 3-49 
compiling an extension 3-48 
cond special form 5-10 


cons 2-13 


construct 
see cons 


control argument 
~line_length 5-3 
~line_speed 5-3 
~page_length 5-3 
-query 5-2 
-terminal_type 5-2 


conversion 
character/number 3-43 
number/character 3-43 
CTL, 5-2 


CTL functions 


see DCTL . 
Ctol function 3-43 
cur~hpos function 3-6 
curchar function 3-40 
current-buffer variable 3-29 


current-buffer-mode variable 
3-22, 3-38 


cursor position 
cur-hpos 3-6 
go-to-hpos 3-6 
predicates reflecting 3-11 


DCTL-clear-rest-of-screen 
function 5-6 


DCTL-delete-chars function 
5-8 


DCTL-delete-lines function 
5-7 


DCTL-display-char-string 
function 5-5 


DCTL-epilogue function 5-7 


DCTL-init function 


2h Te) 
5-6 


DCTL-insert-char-string 
function 5-7 


DCTL-insert-lines functions 
5-7 


DCTL-kill-line function 5-6 


DCTL-position-cursor function 
~ (6=5 


DCTL-prologue function 5-7 


DCTL-scroll-down-region. 
function 5-9 


DCTL-scroll-up-region function 


debug-e function 3-48 
debugging 3-48, 4-1 


decimal-rep function 
3-15 


2-16; 


declarations 3-49 
default specification 3-63 


defcom 3-61, 3-62, 3-63, 3-64, 
3-65, 3-66, 3-67, 3-68 
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defcom (cont) 


keywords 3-61 

&arguments 3-63, 3-64, 
3-66, 3-68, 3-69 

&cleanup 3-66, 3-68, 3-69 

&completions 3-66, 3-67 

&documentation 3-66 

&epilogue 3-65, 3-68, 
3-69 

&inverse 3-67, 3-68 

&negative-function 3-66, 
3-68 


&numeric-~argument 3-61, 
3-62, 3-66, 3-668 


&numeric-function 3-62 
&prologue 3-65, 3-68 
&undo 3-67 
Gefprop function 3-37 
defprop special form 3-37, 
3-50. : 
defun special form 2-1, 2-7 


defvar special form 3-19 


delete-white-sides function 
3-13 
delete-window function 3-56 
deleting 
line 3-3 
region 3-3 
der-wahrer-mark variable 3-22 
destroy-buffer-contents 
function 3-29 


dispatch-on-current-char 
special form 3-42 


dispatch-on-lefthand-char 
special form 3-42 
display 3-25 


display-as-printout special 
form: 3726 


display-buffer-as-printout 
function 3-25 


display-com-error function 
3-17 | 


display-com-error-noabort 
Eunction 3-17 
display-error function 3-16 


display-error-noabort function 


K fae! a a 
display-error-remark function 
3716 
division 
//€unetion 2-11 


do special form 5-11 
do-forever special form 2-9 


do-times special form 3-5 


documenting requests 3-50 
&doc 3-66 
dont-notice-modified-buffer 
function 3-29 
EB 
element 2-13 


else keyword 2-7 


empty-buffer-p predicate 3-12, 
3726 


end-local-displays function 


entry value 4-3 
env-dir global variabie 3-20 


eolp predicate 3-10 
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epilogue 3-65 


eq predicate 2-6, 3-40, 5-4 


error 3-8.i 
Emacs error system 
functions 3-60 
handling 4-1 
table. 3-59 
trap entry 4-3 


3-60 


error-table function 3-60 


error_table_ function 3-59 


ESC && (ldebug) 4-4 


ESC G (ldebug) 4-2, 4-3 


ESC global variable 3-16 


ESC L (ldebug) 4-4 


ESC P (ldebug) 4-4 


ESC R (ldebug) 4-4 


ESC T (ldebug) 4-3 


ESC “C(lisp) 3-49 


ESC “S (ldebug) 4-5 


escape character (Lisp) 2-11 
establish-local-var funetion 
3-21 


evaluation 2-2 
conditional 2-7 
of functions calls 
of numbers 2-3 
of strings 2-3 


23 


ww 
aa 


exe 10 
Ss evaluation 


cut 
ee 
explode function 2-18 


explodec function 3-27 


1-5 


extension 
definition of i-i 
e cline_ 3-58 
F 
file 


reading/writing 3-3 


fill-mode-delimeters variable 
3-39 


find-buffer-in-window function 
3-52 


find-file-subr function 3-3 


firstlinep predicate 3-11 


fixp predicate 2-6 
form 2-2, 2-3, 27-4, 2716 
not 2-11 
special 2-6 
and 2-i1 
cond 5-10 
Gefprop 3-37, 3-50 
defun 2-7 
defvar 3-19 
dispatch-on-current-char 
3-42 
dispatch-on-lefthand-char 
3-42 

display-as-printout 
ao. 5-11 
do-forever 
do-times 
get. 3-27 
go 2-10 
Tf 257 
if-at 3-41 
1f-back-at 
let 2-9 
Of) 2712 
prog 2-i0 
progl. -2=12 
progn 2-il1 
protect 3-10 
putprop 3-27 


3-26 


2-9 
329 


3-41 
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form (cont) 
special 
save-excursion 3-7 
save-excursion-buffer 
3-29 
save-excursion-on-error 
3-7 
setq 2-8 
-unwind-protect 3-9 
with-mark 3-6 
without-modifying 
without-Ssaving 3-8 
stop-doing 2-9 


3-8 


format-to-col function 3-14 


forward~-search function 3-3 
forward-search-in-line 
function 3-15 


fpathname variable 3-22 


~— wee we wer wee 


funcall function 3-38, 3-39 
function 2-1, 2-4 
add-error-code 

append 2-16 
apply-catenate 
ascii 3-43 
assert-minor-mode 
buffer-kill 3-29 
buffer-on-display-in-window 
3-56 
car 2-13 
catenate 
edr 2-13 
charscan-table 
command-quit 


3-60 


3=39 


3e32 


3733 
ais 


comout-get-output 3-59 

cons 2-13 

CtoI 3-43 

cur-hpos. 3-6 

curchar 3-40 

DCTL-clear-rest-of-screen 
5='6- 

DCTL-delete-chars 5-8 

DCTL-delete-lines 5-7 


function (cont) 
DCTL-display-char-string 


5-5 
DCTL-epilogue 5-7 
DCTL-init 5-4 


DCTL-insert-char-string 5-7. 
DCTL-insert-lines 5-7 
DCTL-kill-line 5-6 


DCTL-position-cursor 5-5 


DCTL-prologue 5-7 
DCTL-scroll-down-region 5-9 
DCTL-scroll-up-region 5-8 
decimal-rep 2-18, 3-15 
definition 2-1 
delete-white-sides 3-13 
delete-window 3-56 
destroy-buffer-contents 
3-29 
display-buffer-as-printout 
3=25 
display-com-error 3-17 
display-com-error-noabort 
S17 
Gisplay-error 32-16 
display-error-noabort 3-17 
display-error-remark 3-18 


dont-notice-modified-buffer 


3-29 
Emacs requests 3-i 
, exceptions 3-2 
end-local-displays 3-24 
error-table 3-60 
error_table 3-59 
establish-local-var 3-21 
explode 2-18 
explodec 3-27 
e cline 3-58 
find-buffer-in-window 3-52 
find-file-subr 3-3 
Eor: CTLs: 5=2 
format-to-col 3-14 
forward-search 3-3 
forward-search-in-line 3-15 
full-redisplay 3-4, 3-32, 
3-33 
funcall 3-38, 3-39 
get-char 3-43 
get-search-string 3-57 
go-to- Apos 3-6 
go-to-mark 3-6 
Go-to-or-create-cutier. 3-3, 


So2i 
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function (cont) 


init-local-displays 3-24 
insert-string 3-4 
ItoC 3-43 
kilirpep: 36.1, Br5.1, 
: B= 1961 
kitderine=top 3-6, 7) -B2S.1, 
Brio. 
killsave-string 3-8 
lefthand-char 3-41 
list 2-14 
Lise. 2215 
local-display-current-line 
3=25 
local-display-generator 
3-24 
maknam 2-18, 3-27 
mape 3-39 
minibuffer-clear 3-17 
minibuffer-clear-all 
minibuffter-print 3-15 
minibuffer-print-noclear 


3-16 


3-17 
minibuffer-response 3-16 
ncone 2-16 
negate-minor-mode 3-39 
next-line 3-3 
nreverse 2-16 
point-mark-to-string 3-3, 

3-14 
prev-line 3-3 


process-char 3-44 
read-from-string 2-19 
read-in-file 3-3 
redisplay 3-31 
redisplay-current-window 
~relative 3-4, 3-33 
regexp-search 3-3 
regexp~Search-in-line 
register-local-variable 
3-20 
register-option 
release-mark 3-5 
report-error 3-60 
report-error-noabort 
Function 3-60 
reverse 2-16 
reverse~regexp~search 
B-8, B-25 
reverse-search 3-3. 
reverse-search-in-line 
ring-tty-bell 3-18 


3715 


3-35 


3=15 


function (cont) 


rotate-kill-ring 3-8.1, 


B=-5.1, B=25 
Rprine 5-4 
Rtyo 5-4 


search-back-first 
-charset-line 3-34 
search-back-first-not 
-charset-line 3-34 
search-charset-backward 
3-34 
Search-charset-forward 3-34 
search-failure-annunciator 
3-57 
search-for-first 
-charset-line 3-34 
search-for-first-not 
-charset-~line 3-34 
search-not-charset-backward 
3-34 
search-not-charset-forward 
3-34 
select-buffer-find-window 
3-54 
select-buffer-window 
select-window 3-56 
set-buffer-self-destruct 
3-28 
set-key 3-38 
set-mark 3-5 
skip-back-to-whitespace 
3-13 
skip-back-whitespace 3-13 
skip~back-whitespace-in-line 
3-13 
skip-over-whitespace 3-13 
skip-over-whitespace-in-line 
3-13 
skip-to-whitespace 
Stringlength 5-5 


3=53 


s=13 


view-region-as-lines 3-25 
whitespace-to-hpos 3-14 
window-adjust-lower 3-56 
window-adjust-upper 3-56 
window-info 3-56 
wipe-point-mark 3-3, 3-5 
write-out-file 3-3 
funetion call 2-4 


syntax 2-3 
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G 
get Special form 3-27 
get-char function 3-43 


get-search-string function 
37-57 


given-tty-type variable 5-4 


global variable 


nil 2-8 
see variable, global 
t 2-8 


go special form 2-10 


go-to-~hpos function 3-6 
as predicate 3-6 
go~to-mark function 3-6 


go-to-or-creat-buffer function 


go-to-or-create-buffer 


3-26 
go-to-or-create-buffer 
function 3-26, 3-27 

H 
heterophanic request 3-52 
hook 

mode 3-23 

I 

ibase global variable 2-19 


if special form 2-7 


Syntax 2-7 


-* 


if-at special form 


iss 


if-back-at special form 3-41 
indicator 3-26 


init-local-displays function 
3-24 

insert-string function 3-4 

interned symbol 3-26 


3-43 


keyword 
else 2-7 
kill-pop function 
B=o.2, Bol19s2 


fast = ri 


killsave-string function 3-8 


L 


label 2-10 


last-minibuffer-response 
variable 3-16 


lastlinep predicate 3-11 
ldebug mode 
ldebug-display-where 
~editor-was 
ESC *S 4-5 


ldebug-list-breaks 
ESC L 4-4 


ldebug-reset~break 
ESC R 4-4 
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ldebug-return-to-emacs macro character 


-top-level backquote A-i 
ESC G 4-2 comma A-1 
ldebug-trace-stack major mode 
ESC T 4-3 see mode 
lefthand-char function 3-41 maknam function 2-18 
let special form 2-9 maknem function 3-27 


Syntax 2-10 
mape function 3-39 
line-is-blank predicate 3-12 


mark 3-5 
Lisp debug mode go-to-mark 3-6 
see ldebug predicates 3-11 
release-mark 3-5 
Lisp macro A-1 Save-excursion 3-7 
see macro set-mark 3-5 
temporary 3-5 
Lisp macros 3-49 wipe-point-mark 3-3 
with-mark 3-6 
List: 2-13 
Mark-at-current-point-p 
list function 2-14, 2-15 predicate 3-11 
loading an extension 3-1, mark-on-current-line-p 
3-45 predicate 3-12 
local display 3-24 mark-reached predicate 3-11 
local variable mark-~same-line-p predicate 
see variable, local 3-12 
local-display-current-line memgq predicate 3-39 


function 3-25 
minibuffer 3-15 


local-display-generator functions 3-16, 3-17 
function 3-24 yesp 3-12 

looking-at predicate 3-2, minibuffer-clear function 
Taos 3=17 

looping minibuffer-clear-all function 


3-16 


w 


see do-forever 2- 


minibuffer-print function 
M 3-15 


minibuffer-print-noclear 
macro 2-17 function 3-17 
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minibuffer-response function numarg global variable 3-4 


3-16 
number/character conversion 
minor mode 3-43 
see mode . 
Numeric arguments 3-4 
mode do-times 3-5 
hook 3-23 
ldebug 4-1 nuwindows variable 3-55 
major 3-37 
Minor 3-37, 3-39 
fe) 
mode~hook 3-39: 
multiple windows. obarray 2-12, 3-26 


see windows 
object 2-6, 2-18 


multiplication 
*function- .2=1 . object program 3-48 
operand 2-10 
: option 3-35 
names or special form 2-11 


choosing 3-36 
ospeed variable 5-3 
neonc function 2-16 


negate-minor-mode function , P 
3=39 
negative function 3-66 Parentheses 2-3 
negative-function defcom per-buffer variable 
‘ keyword 3-66 ' see variable, local 
next-line function 3-3 point-mark-to-string function 
3°35. 3714 


nil global variable 2-8 
point>markp predicate 3-11 
nil symbol 3-4 
pop-up window mode 3-53 
NL global variable 3-16 
| predicate 2-5 


not form 2-ii1 < 2-5 
= 2-5 
nreverse function 2-16 > 2-5 
alpnaliessp 2-6 
maa) 7 RWreaAniAaka bo fe at 2-219 
bb Md abe ob WE eUMILWVGaLeE & Wad ae w ae ho 


at=begqinning-ot=butter 3-11 
null-stringp predicate 3-12 at-enc-of-butter 3-11 
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predicate (cont) 


at-white-char 3-11 

back-at 3-12 

Dolo. 32-17 

buffer-on-display-in-window 
3-56 


charset-member 3-34 
empty-buffer-p 3-12, 3-28 
eclp: 3-10 

eq 2-6, 3-40; 5-4 
firstlinep 3-11 


fixp 2-6 
go-to-hpos 3-6 
lastlinep 3-11 


line-is-blank 3-12 

Looking=at’. 3-2, 3-22 

mark-at-current-point-p 
sid 

mark~on-current-line-p 

mark-reached 3-i1 

mark-same-line-p 3-12 

memqg 3-39 

null 2-6 

nuli-stringp. S-12 

point>markp 3-11 

Samepnamep 2-6 

stringp 2-6 

symbolp 2-6 

yesp 3-12 


S12 


prev-line function 3-3 
previous-buffer variable 3-29 
print function 2-2 

printname 2-12 


problem 
monitoring 3-21 


proces-dir global variable 
3-20 


process-char function 3-44 
prog special form 2-10 
progi special form 2-12 


progn special form 2-i1 


L=17 


prologue 


3765 
prompting 
&prompt 3-64 
minibuffer-response 3-16 
property 2-16, 3-26 
documentation 3-50 


protect special form 3-10 


putprop special form 3-27 
R 
read-from-string function 
2-19 

read-in-file function 3-3 
read-only-flag variable 3-22 
redisplay 3-31, 3-33 

3=31 


redisplay function 


redisplay-current-window 


~relative function 
3-33 


3-4, 


regexp-search function 3-3 


regexp-search-in-line function 
3=15 


region 


copying 3-3 
deleting 3-3 


region scrolling 5-8 


region-scroll-availablep 
variable 5-8 


register-local-variable 
function 3-20 


register-option function 3-35 
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registering a variable 
functions 3-20 


release-mark function 3-5 
report-error function 3-60 
return function 2-9 


returned value 2-1 


reverse-regexp-search function 
reverse function 2-16 
reverse-search function 3-3 


reverse-search-in-line 
Function 3-15 
ring-tty-bell function 3-18 


rotate-kill-ring funceien 
$-6..17. 3-35.14; 8-25 
rplaca function 2-15 
rplacd function 2-15 
Rprine function 5-4 


Rtyo function 5-4 


Samepnamep predicate 2-6 


Save-excursion special form 
3-7 


Save-excursion-buffer special 
form 3-29 


Save-excursion-on-error 
Special form 3-7 


a=33 


scrolling 
region 5-8 


search-back-first-charset-line 
function 3-34 


search-back-first-not 
~charset-line function 3-34 
search-charset-backward 
function 3-34. 


search-charset-forward 
function 3-34 


search-failure-annunciator 
function 3-57 


search-for-first-charset-line 
function 3-34 


search-for-first-not 


-~charset-line function 3-34 


search-not-charset~backward 
function 3-34 


search-not-charset-forward 


function 3-34 
searching 3-57 
forward-search-in-line 3-15 
 foward-search 3-3 
get-search-string 3-57 
regexp-search 3-3 
regexp-search~in-line 3-15 


reverse-regexp-search 8-8, 
B-25 | 

reverse-search 3-3 

reverse-search-in-line 3-15 

search-failure-annunciator 
3-57 


select-buffer-find-window 
function 3-54 


select-buffer-window function 
3-53 
select-window function 3-56 


selected-window variable 3-55 
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set-buffer-self-destruct 
function 3-28 


set-key (ESC %) 3-1 

set-key function 3-21, 3-38 
set-mark function 3-5 
set-permanent~key (ESC X) 3-i 
setq special form 2-8 


skip-back-to-whitespace 
function 3-13 


skip-back-whitespace function 
3713 


skip-back-whitespace-in-line 
function 3-13 


skip-over-whitespace function 
S713 


skip-over-whitespace-in-line 
function -32-15 


skip-to-whitespace function 
3-13 

special form 

defcom 3-61 

see form 
special varibale 

see variable . 

global 

stop-doing form 2-9 
String form 3-40 
Stringlength function 5-5 
stringp predicate 2-6 


subtraction 
-function 2-1 


symbol 2-6, 2-16 
definition of 2-12 


- symbol (cont) 


interned 3-26 
property 3-26 
registry 3-26 


symbolp predicate 2-6 


eh 


t global variable 


2-8 


tab-equivalent variable 


temp-mark variable 3-5 


temporary 


mark 3-5 
variable 2-10 


terminal support 


terminal type file 


the-mark global variable 


trace 4-5 


= ag | 
faa 


tracing function 4-4 


tty-type variable 


U 


5-4 


37-22 


3=5 


unwind-protect special form. 


3-9 


variable 2-3 


1-12 


binding 2-3 
current-buffer 
Gefvar 3-19 
given-tty-type 
global 2-4, 3-1 
*nopoink’. 2-19 
alm-mode-hook 


3=29 
5-4 


3; 3°35 


3=23 
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variable (cont) 


global 
base 2-19 


buffer-creation-hook 3-24 


buffer-destruction-hook 
3724 
buffer-entrance-hooks 
3-24 
buffer-exit~-hook 3-24 
character object 3-41 
close-line-hook 3-24 
current-buffer 3-27 
env-dir 3-20 
ESC 3-16 


fill-mode-delimeters 3-39 


fortran-mode-hook 3-23 
ibase 2-19 
ldebug-mode-hook 3-23 
lisp-mode-hook 3-23 
Mail-mode-hook 3-23 
nil 2-8 
NL. 3-16 
numarg 3-4 

| pli-mode-heek 3 
Pprocess-dir 3-20 
rmail-mode-hook 3-23 
see mode hook 


t 2-8 

the-mark 3-5 

ye re fa 
last-minibuffer-response 

3716 

ldebug-level 4-2 
local 3-20 

automatically registered 

3-22 


buffer-minor-modes 3-39 
current-buffer-mode 3-38 
nuwindows 3-55 
option 
ldebug-base 4-2 
ldebug-ibase 4-2 
ldebug-prinlength 4-2 
ldebug-prinlevel 4-2 
ospeed 5-3 
parameter 2-4 
previous-buffer 3-29 
region-scroll-availablep 


5-8 
registering 3-20 
selected-window 3-55 


variable (cont) 


special 

se global 
temp-mark 3-5 
temporary 2-4, 2-9 


trace-break-fun 4-7 
trace-printer 4-7 
tty-type 5-4 


view-region-as-lines function 
$225 


whitespace 
functions 3-13 
management 3-13 


whitespace-to-hpos function 
3-14 


windau 3-33 


“number 3-55 
pop-up window mode 3-53 
selected 3-55 


window-adjust-lower function 


window-adjust-upper function 


Window-info function 3-56 


windows 
multiple 3-52 


wipe-point-mark function 3-3, 


with-mark special form 3-6 


without-modifying special form 
3-8 


without-saving special form 
3-8 


write-out-file function 3-3 
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».4 
X global variable 5-4 
x 


Y global variabie 5-4 


yesp predicate 3-12 
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